Exchange an authorization code or refresh token for an access token (OAuth, no sign-in)
POST /api/hr/v1/oauth/token
Module: HR · operationId: oauthToken · Tag: Auth · Auth: none
The OAuth 2.1 token endpoint (form-encoded). authorization_code needs code, redirect_uri (exactly as in the authorization request), code_verifier (PKCE S256) and client_id; a code lives 60 seconds and is used once – presenting it again revokes its grant. refresh_token needs refresh_token and client_id; every refresh rotates the refresh token (it lives 30 days unused). A rotated refresh token presented again within 5 seconds is only refused; later it revokes the whole grant. The access token works like an exchanged API key token: 15 minutes, authMethod: oauth, the current permissions of the person (without identity:admin and tenant:token:generate; the person must still hold tenant:token:generate) or of the service account. Every refusal of a code or refresh token is invalid_grant. Rate limited per client address (10 per second, bursts up to 50).
For an app of a tenant (OpenID Provider, AUTH.md "OpenID Provider") the answer is OpenID Connect's: an ES256 id_token (pairwise sub, nonce, auth_time, at_hash; name, email, groups by scope), an opaque access_token the userinfo endpoint alone accepts (15 minutes), scope, and a refresh_token only with offline_access. A confidential app authenticates with client_secret_basic or client_secret_post (401 invalid_client otherwise); PKCE is required for every client.
The first-party mobile app is a public client like MCP (no secret). Its access token is a session token (authMethod: mobile, 15 minutes, with the session id sid) and every refresh rotates the refresh token. A refused refresh of a mobile grant revokes it and announces hr.mobile_session.ended.
Request body
application/x-www-form-urlencoded (required)
client_id(string, required)grant_type(string, required): (one ofauthorization_code,refresh_token)client_secret(string): A confidential app's secret (client_secret_post; or HTTP Basic)code(string)code_verifier(string)redirect_uri(string)refresh_token(string)
Responses
- 200 Tokens (an app's answer adds id_token and scope; refresh_token only with offline_access) (
application/json) - 400 OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (
application/json) - 401 OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (
application/json) - 429 Too many requests
- 503 OAuth error (RFC 6749 §5.2, RFC 7591 §3.2.2) (
application/json)
Fields of the 200 answer:
access_token(string, required): JWT; treat it as opaqueexpires_in(integer, required): Secondsrefresh_token(string, required): The next refresh token; the presented one is used uptoken_type(string, required)id_token(string): Apps only – the ID token (ES256)scope(string): Apps only – the granted scopes
Example 200 answer:
{
"access_token": "EXAMPLE.eyJhdXRoTWV0aG9kIjoib2F1dGgifQ.EXAMPLE-SIGNATURE",
"expires_in": 900,
"refresh_token": "ccr_EXAMPLE-refresh-token",
"token_type": "Bearer"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/oauth/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-binary @body