ConnectCloud Developers

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 of authorization_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 opaque
  • expires_in (integer, required): Seconds
  • refresh_token (string, required): The next refresh token; the presented one is used up
  • token_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

View as Markdown · Interactive reference · OpenAPI