## 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:

```json
{
  "access_token": "EXAMPLE.eyJhdXRoTWV0aG9kIjoib2F1dGgifQ.EXAMPLE-SIGNATURE",
  "expires_in": 900,
  "refresh_token": "ccr_EXAMPLE-refresh-token",
  "token_type": "Bearer"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-binary @body
```
