Get OAuth2 token

POST

/idp/oauth2/token

Issues OAuth2 tokens used to authenticate every API call. The security foundation of the platform.

Supports four flows depending on the integration type:

• client_credentials — server-to-server access to the Zertiban API. The clientId / clientSecret pair travels in the Authorization header as HTTP Basic, not in the body. Returns a short-lived access_token (default expires_in is 900 seconds / 15 minutes). Send it on every subsequent API call as Authorization: Bearer {access_token}, alongside x-tenant-id: {businessUuid}.
• authorization_code + PKCE — browser-driven login for the Zertiban dashboard.
• refresh_token — exchange a refresh token for a new access token (typically for the dashboard session).
• urn:ietf:params:oauth:grant-type:token-exchange — tenant-to-tenant switch within the same user session. The dashboard sends the current access_token as subject_token and the target tenant UUID as audience. Returns a new access_token with the roles and authorities of the target tenant. The original token is not revoked. The scope and resource parameters are not accepted and will produce a 400 invalid_request.

Always read expires_in from the response and refresh before expiry to avoid 401 errors.

Autorizaciones

clientSecretBasic

OAuth2 client authentication for the token endpoint. The
clientId / clientSecret pair is sent as HTTP Basic Auth in
the Authorization header (e.g. curl -u clientId:clientSecret,
Python requests auth=(id, secret)), not in the request body.
Required by default for confidential clients.

Tipo

HTTP (basic)

Cuerpo de la petición

application/x-www-form-urlencoded

object

One of

object

Valores válidos"authorization_code"

Formato"uri"

PKCE code verifier (original random string).

object

Body for the client_credentials grant — server-to-server
authentication for Zertiban API consumers. The clientId and
clientSecret travel as HTTP Basic Auth in the Authorization
header, not in this body.

Must be client_credentials.

Valores válidos"client_credentials"

Optional space-delimited scopes. The scope parameter is
not required for standard Zertiban API access.

REQUIRED when scope includes web_app. UUID of the tenant the token is being issued for. The value is embedded as the tenant_id claim in the resulting access token.

Formato"uuid"

object

Valores válidos"refresh_token"

Optional reduced scope set.

object