Register a customer-signed JWT

Before you begin

Your client needs an RSA signing key of at least 3072 bits and a currently valid X.509 public certificate that permits digital signatures. Generate and retain the private key in an approved secret manager or hardware security module.

Register only the public certificate. Never place a private key or private-key PEM in Dashboard, source, logs, tickets, or generated packages.

Register the signing identity

1. Open the integration's Authentication setup.
2. Choose Customer-signed JWT.
3. Enter the exact issuer and subject values the client will send as iss and sub.
4. Paste the PEM public certificate that corresponds to the protected private key.
5. Save the authentication method and record the supplied Customer API audience.

Issue a token

Sign tokens with RS256. Include exactly one base64 DER leaf certificate in the protected x5c header, the registered issuer and subject, the audience supplied by Wavac, a short expiration, and only the granted scopes.

This commented JSON is for learning. Remove every comment before serializing and signing the JWT.

// Protected header: remove comments before encoding this JSON.
{
  // RS256 is the supported algorithm for customer-owned signing keys.
  "alg": "RS256",
  // typ identifies the compact signed value as a JWT.
  "typ": "JWT",
  // x5c contains one base64 DER public leaf certificate.
  "x5c": ["base64-DER-public-certificate"]
}

// Payload: use the values registered for this integration.
{
  "iss": "https://customer.example",
  "sub": "production-export",
  "aud": "customer-api",
  "scope": "customer.discovery.read customer.data.read",
  "iat": 1788278400,
  "exp": 1788278700
}

The issuer, subject, certificate, audience, token lifetime, scopes, customer, and active integration must all satisfy the registered method and policy.

Verify the credential

Send a discovery request with the signed token:

GET /api/customer/v1/discovery
Authorization: Bearer <customer-signed-token>
Accept: application/json

A 200 response confirms that the token and current policy permit discovery. Use resolve Customer API errors for a 401 or 403 response; do not expose the token while troubleshooting.

Rotate or revoke the key

Rotate the method by registering the replacement public certificate with its issuer and subject, then switch the client atomically to the matching protected private key. Rotation invalidates tokens tied to the previous registered values.

If the private key might be exposed, replace the registered signing identity immediately, revoke access where available, and remove exposed key material from local and CI artifacts.