API credentials

A subscription in your API Portal holds its own credentials. The credential type comes from the plan's security level: an API key, a Client ID and Client Secret, or Private Key JWT. A developer creates and manages them on the subscription's Details tab, in the authorization section.

What credential types can a subscription use?

The plan's security level sets the credential type. A subscription receives one of the types below. The plan, not the developer, chooses it.

Two further types exist for specific gateways: an intermediate server-to-server JWT and an advanced code flow. The plan's security level determines which one applies.

How does a developer get credentials?

When a subscription is Active and has no credentials yet, the developer clicks Create Authorization and confirms. The portal generates the credential and shows it in full once, with a warning to save it.

1. The developer opens the subscription and finds the authorization section on the Details tab.
2. They click Create Authorization and confirm. The portal generates the credential.
3. The portal shows Credentials created successfully! with the full values and the warning to save them now.
4. They copy and store the values, then click I've saved my credentials, continue. Leaving the page first asks them to confirm.
5. From then on, the portal shows only a masked value. The full key or secret can't be shown again.

Creating, regenerating, and rotating credentials need Full API keys access in the team. Members with Read Only API keys access can see the masked credentials. See Teams.

How does a developer get a first access token?

For a Client ID and Client Secret, the panel with the new credentials has a Generate Access Token section. Generate Token requests an access token through your API Portal and shows it with a copy button.

The button works only while the new secret is on screen, because the portal never shows the secret in full again. Afterwards, the developer requests tokens from your token endpoint with the Client ID and the secret they saved. When the credential carries one, Show example displays a sample request.

What is the difference between Regenerate and Rotate Secret?

Regenerate replaces the whole credential: it revokes the current one and issues a new one, so an OAuth2 client gets a new Client ID and secret. Rotate Secret keeps the Client ID and issues only a new secret. With either action, the old secret stops working at once.

The authorization section shows one of the two buttons. With the standard Authorization Servers, Keycloak, Auth0, and Duende, developers always see Regenerate Credentials. See Authorization Servers.

How does Private Key JWT work?

With Private Key JWT there is no client secret. The developer provides a JWKS URL, an HTTPS address where their public signing keys are hosted. The portal registers an OAuth2 client, and the developer authenticates by signing a JWT with the matching private key.

1. On a Private Key JWT plan, the subscription starts without a client. The developer enters a JWKS URL and saves it.
2. The JWKS URL must use HTTPS. The portal rejects anything else with JWKS URL must use HTTPS.
3. The developer clicks Create Authorization. The portal registers a client at your authorization server.
4. The authorization section then shows the Client ID, the Token endpoint, the Authentication method, the JWKS URL on file, and the Supported signing algorithms: RS256, ES256, or PS256.

To rotate signing keys, the developer uses Edit JWKS URL and points the client at the new key set. There is no client secret, so a Private Key JWT subscription never offers Rotate Secret.

Private Key JWT registration needs a Keycloak Authorization Server. See Authorization Servers for how Dynamic Client Registration provisions a client per subscription.

When are credentials unavailable or revoked?

Credential availability follows the subscription status and, on a sandbox plan, its pipeline phase. The portal shows a clear state in each case.

Where to next