nt24-idp) issue short-lived
access tokens bound to your IntegrationOrganization. There is no per-user
login flow, every API call is authenticated by a bearer token minted from your
client credentials.
Why client_credentials
- No user in the loop. API calls are server-to-server; no browser redirects or login prompts.
- Short-lived tokens. Access tokens expire quickly (typically 5 minutes). Leaked tokens auto-expire.
- Rotatable secrets. Your
client_secretrotates via Keycloak without changing any integration code. - Standard tooling. Works with every OAuth2-compatible HTTP client (Spring, Axios, httpx, etc.).
Token endpoint
application/x-www-form-urlencoded:
access_token in every API request as Authorization: Bearer <token>.
Token caching
Tokens are valid forexpires_in seconds (typically 300). Cache the token
and refresh a minute before expiry.
Secret rotation
Rotate yourclient_secret via Keycloak admin API or by contacting support
for a regeneration. Process:
- Request a new secret (both old and new valid during rotation window).
- Update your backend to use the new secret.
- Old secret is revoked after you confirm the cutover.
Organization and partner scoping
Your Keycloak client is linked to exactly oneIntegrationOrganization. The
organization defines:
- Authorized partners: the
TradePartnerUUIDs you can act on behalf of. Every endpoint that touches partner-scoped data requires the partner UUID in the URL path (/partners/{sellerId}/...). - Capability flags: features gated on organization entitlement (e.g.
allowMarketplaceLedKyc,rateLimitTier). - DPA acceptance: Data Processing Agreement version and acceptance
timestamp. Requests are rejected with
403if the DPA is missing or outdated.
GET /v1/me at startup.
Troubleshooting
403 Forbidden on API call
403 Forbidden on API call
- Partner path (
{sellerId}) not in your authorized partners list. CheckGET /v1/me. - Missing capability for the endpoint (e.g. Mode A KYC,
MARKETPLACE_LED, which is not available yet and answers403for every organization). - DPA not accepted for your organization.
invalid_client response from token endpoint
invalid_client response from token endpoint
- Wrong
client_idorclient_secret. - Client disabled in Keycloak, contact support.
- Service Account Roles disabled on the client configuration.
invalid_grant response from token endpoint
invalid_grant response from token endpoint
grant_typemust be exactlyclient_credentials(lowercase).- Do not include
usernameorpassword, those are for a different grant flow.
Next
Quickstart
Call your first endpoint.
Error reference
Full RFC 7807 problem type catalog.