OAuth2 Token Management

Production - POST /api/v1/oauth2/token, /revoke, /introspect

The token endpoint exchanges authorization codes for tokens, refreshes existing tokens, and issues client credentials tokens. The revocation and introspection endpoints provide token lifecycle management.

6.8.6Token Exchange

Authorization Code Exchange

curl -X POST http://localhost:8081/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&\
code=abc123&\
redirect_uri=https://bi.example.com/callback&\
client_id=matih_client_a1b2c3d4e5f6&\
client_secret=secret_x9y8w7v6u5t4s3r2q1p0&\
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

Client Credentials Grant

curl -X POST http://localhost:8081/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "matih_client_a1b2c3d4e5f6:secret_x9y8w7v6u5t4s3r2q1p0" \
  -d "grant_type=client_credentials&scope=queries:execute+catalog:read"

Refresh Token

curl -X POST http://localhost:8081/api/v1/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&\
refresh_token=eyJhbGciOiJIUzI1NiJ9...&\
client_id=matih_client_a1b2c3d4e5f6&\
client_secret=secret_x9y8w7v6u5t4s3r2q1p0"

Token Response

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiJ9...",
  "scope": "openid profile dashboards:read"
}

The token endpoint also accepts JSON body (Content-Type: application/json).

6.8.7Token Revocation

curl -X POST http://localhost:8081/api/v1/oauth2/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=eyJhbGciOiJIUzI1NiJ9...&\
token_type_hint=access_token&\
client_id=matih_client_a1b2c3d4e5f6&\
client_secret=secret_x9y8w7v6u5t4s3r2q1p0"

6.8.8Token Introspection

curl -X POST http://localhost:8081/api/v1/oauth2/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "matih_client_a1b2c3d4e5f6:secret_x9y8w7v6u5t4s3r2q1p0" \
  -d "token=eyJhbGciOiJIUzI1NiJ9..."

Response

{
  "active": true
}

OAuth2 Token Claims

OAuth2 access tokens include these additional claims:

Claim	Type	Description
`client_id`	String	The OAuth2 client identifier
`scope`	String	Space-separated scopes
`user_id`	Long	User ID (not present for client credentials)
`tenant_id`	Long	Tenant ID
`token_type`	String	`access_token` or `refresh_token`
`grant_type`	String	Present for client credentials tokens

Error Responses

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Error	Description
`invalid_request`	Missing required parameter
`invalid_client`	Client authentication failed
`invalid_grant`	Invalid authorization code or refresh token
`unsupported_grant_type`	Grant type not supported

Authorization Code Overview