Authorization Code Flow

Production - GET/POST /api/v1/oauth2/authorize

The authorization code flow allows third-party applications to obtain access tokens on behalf of users. The MATIH implementation supports PKCE (RFC 7636) for public clients.

6.8.3Flow Diagram

Client App          IAM Service             User
    |                    |                    |
    |--- /authorize ---->|                    |
    |  (client_id,       |--- Login page ---->|
    |   redirect_uri,    |                    |
    |   scope, state)    |<-- Credentials ----|
    |                    |                    |
    |<-- Redirect -------|                    |
    |  (code, state)     |                    |
    |                    |                    |
    |--- /token -------->|                    |
    |  (code,            |                    |
    |   client_secret,   |                    |
    |   code_verifier)   |                    |
    |<-- Tokens ---------|                    |

6.8.4Authorization Request (GET)

# Redirect the user to this URL
GET http://localhost:8081/api/v1/oauth2/authorize?\
  response_type=code&\
  client_id=matih_client_a1b2c3d4e5f6&\
  redirect_uri=https://bi.example.com/callback&\
  scope=openid+profile+dashboards:read&\
  state=random_state_value&\
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&\
  code_challenge_method=S256

Authorization Request Parameters

Parameter	Required	Description
`response_type`	Yes	Must be `code`
`client_id`	Yes	Registered client ID
`redirect_uri`	Yes	Must match registered redirect URI
`scope`	No	Space-separated list of scopes
`state`	Recommended	CSRF protection token
`code_challenge`	For PKCE	Base64url-encoded SHA-256 hash of code verifier
`code_challenge_method`	For PKCE	Must be `S256`
`nonce`	No	OpenID Connect nonce

Authorization Response

On success, the user is redirected to the callback URL with an authorization code:

https://bi.example.com/callback?code=abc123&state=random_state_value

6.8.5Authorization Request (POST)

The POST variant returns a JSON response instead of redirecting:

curl -X POST http://localhost:8081/api/v1/oauth2/authorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <user-token>" \
  -d '{
    "responseType": "code",
    "clientId": "matih_client_a1b2c3d4e5f6",
    "redirectUri": "https://bi.example.com/callback",
    "scope": "openid profile dashboards:read",
    "state": "random_state_value"
  }'

Response (200 OK)

{
  "redirectUri": "https://bi.example.com/callback?code=abc123&state=random_state_value"
}

Error Responses

On error, the user is redirected with error parameters:

https://bi.example.com/callback?error=invalid_request&error_description=Invalid+client_id&state=random_state_value

OAuth2 error codes: invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error.

Client Management Token Management