Credentials

Your application proves who it is with one credential: a workload certificate. The same key signs your token requests and your TLS connections. There is no client secret to store, rotate or leak.

How it fits together

1. You generate a P-256 key on your own systems. It never leaves them.
2. You send a certificate signing request (CSR) for it. The platform checks that the request was signed by that key, then issues a certificate for your application. Whatever subject you put in the request is replaced with your application’s identifier.
3. Your application asks the token endpoint for an access token, proving itself with a short assertion signed by the key (private_key_jwt, RFC 7523).
4. It calls the API over mutual TLS with the same certificate, carrying the token. The platform refuses a token and a certificate that name different applications.

Step by step

Create the key and the signing request:

openssl ecparam -name prime256v1 -genkey -noout -out key.pem
openssl req -new -key key.pem -subj "/CN=app_YourApplicationId" -out request.csr

Create the OAuth client once (in the console, or POST /v1/applications/{application_id}/credentials). The response names the client and the token endpoint; it contains no secret.

Request the certificate (console, or POST /v1/applications/{application_id}/workload-certificates with certificate_signing_request). It is issued within seconds; read it back from the same collection when its status is active.

Get a token. The assertion is a JWT signed with ES256 using your key:

Claim	Value
iss, sub	Your client ID (your application ID)
aud	The token endpoint, exactly
jti	A unique value, never reused
exp	At most 60 seconds ahead

curl -s https://auth.sandbox.example/oauth2/token \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$ASSERTION" \
  -d audience=https://api.sandbox.example \
  -d scope="subscriber:resolve status:query"

Call the API over mutual TLS with the certificate and the token:

curl --cert certificate.pem --key key.pem \
  -H "Authorization: Bearer $TOKEN" \
  https://api.sandbox.example/v1/organizations

Rotation

Request a new certificate naming the one it replaces (replaces) and when the old one should stop (overlap_ends_at). Both work during the overlap, so you can redeploy gradually. Then revoke the old one.

Revocation

Revoking a certificate takes effect on the next request: the API refuses it at once, and no new token can be obtained with its key. Revoke with key_compromise if the key may have been exposed.

In the sandbox

The console can generate a key in your browser and save it to your computer, which is convenient for trying things out. Production accepts only keys generated on your organization’s own systems.

Sandbox certificates chain to a sandbox-only root. They are never accepted as genuine.