Developer Docs

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 flow.
  • refresh_token — exchange a refresh token for a new access token.
  • 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.
  • urn:ietf:params:oauth:grant-type:token-exchange (delegated, org-to-org) — a collaborator M2M client exchanges its own client_credentials access token for a new access token acting on behalf of a client organisation. The collaborator sends its own access_token as subject_token and the target organisation UUID as target_tenant (instead of audience). Returns a new access_token whose sub and tenant_id are the target organisation, carrying an act claim that identifies the collaborator. Requires an existing mandate between the two organisations; otherwise the request is rejected with 400 invalid_grant.

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
JSON
{
  
"grant_type": "client_credentials",
  
"scope": "openid profile api"
}

Respuestas​

Token response

application/json
JSON
{
  
"access_token": "string",
  
"token_type": "Bearer",
  
"expires_in": 900,
  
"refresh_token": "string",
  
"scope": "string",
  
"id_token": "string",
  
"issued_token_type": "string",
  
"additionalProperties": "string"
}

Playground​

Servidor
Autorización
Cuerpo

Ejemplos​