Partner & Developer onboarding
API credentials
The credential types a subscription can hold in your API Portal, API key, Client ID and Secret, and Private Key JWT, and the difference between Regenerate and Rotate Secret.
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 these on the subscription's authorization view.
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.
| Credential type | What the developer gets | How they authenticate |
|---|---|---|
| API key | An API key, and optionally a second key. | The key is sent with each request. |
| Client ID and Client Secret | An OAuth2 Client ID and Client Secret. | The developer exchanges them for an access token using the client credentials grant. |
| Private Key JWT | A Client ID and a token endpoint, with no secret. | The developer signs a JWT with their private key. The public key is hosted at a JWKS URL. |
Two further internal 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 creates them from the authorization view. The portal generates the credential and shows it once, with a warning to save it because the secret is not retrievable later.
- The developer opens the subscription and finds the authorization view.
- They create the authorization. The portal generates the credential.
- The full value is shown once. The developer copies and stores it.
- After dismissal, the portal shows an obfuscated value for the secret.
A Pending subscription cannot create credentials. The portal explains that credentials cannot be created until a member of your team has reviewed and approved the access 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 OAuth client gets a new Client ID and secret. Rotate Secret keeps the Client ID and issues only a new secret. The old secret stops working immediately.
| Action | What it changes | What stays | When it is available |
|---|---|---|---|
| Regenerate | Revokes the current credential and issues a new one. For OAuth, a new Client ID and secret. For an API key, a new key. | Nothing of the old credential. | The default. Shown whenever Rotate is not available. |
| Rotate Secret | Issues a new Client Secret. The old secret stops working at once. | The Client ID. | Only on Client Secret Basic when the plan is bound to a custom-provider authorization server. |
The authorization view shows one button. It shows Rotate Secret only when the subscription can rotate, and Regenerate in every other case.
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 OAuth client and the developer authenticates by signing a JWT with the matching private key.
- On a Private Key JWT plan, the subscription starts without a client. The developer provides a JWKS URL and saves it.
- The JWKS URL must use HTTPS. The portal validates it.
- The developer creates the authorization. The portal registers a client at the authorization server.
- The credential view then shows the Client ID, the token endpoint, the JWKS URL on file, and the supported signing algorithms RS256, ES256, or PS256.
Private Key JWT registration requires a Keycloak-bound authorization server. There is no client secret to rotate, so a Private Key JWT subscription does not offer Rotate Secret.
See Authorization Servers for how an authorization server issues OAuth2 tokens and how Dynamic Client Registration provisions a client per subscription.
When are credentials unavailable or revoked?
Credential availability follows the subscription status and the plan lane. The portal shows a clear state in each case.
| State | What the developer sees |
|---|---|
| Subscription is Pending | Credentials cannot be created until your team approves the request. |
| Plan is paid, payment not done | Production credentials are locked until payment is complete. |
| Plan uses a sandbox, not yet in production | A locked production card until your team reviews and approves. |
| Provisioning failed at the authorization server | A "credentials are being provisioned" notice. Recovery is a retry from your dashboard, not from the portal. |
| Subscription is Cancelled | The subscription is cancelled and all keys have been revoked. |