Herald
OpenapiOauth

OAuth authorize endpoint (Authorization Code + PKCE)

Initiates the Authorization Code + PKCE flow: 1. Validates client_id exists and is enabled 2. Validates redirect_uri is in whitelist (exact match only) 3. Validates PKCE code_challenge_method (must be S256 if provided) 4. Stores state token with PKCE parameters in Redis (5 minutes TTL) 5. Redirects to login page with OAuth parameters # Arguments * `realm_id` - Realm identifier * `params` - OAuth query parameters (client_id, redirect_uri, state, response_type, code_challenge, code_challenge_method) # Returns * 302 redirect to login page with OAuth parameters # Errors * 400 - Invalid parameters (missing client_id, redirect_uri, state, or code_challenge) * 400 - Invalid response_type (must be "code") * 400 - Unsupported code_challenge_method (must be "S256") * 404 - Client not found * 403 - Client app is disabled * 400 - Redirect URI not in whitelist

GET
/api/oauth/{realmId}/authorize

Initiates the Authorization Code + PKCE flow:

  1. Validates client_id exists and is enabled
  2. Validates redirect_uri is in whitelist (exact match only)
  3. Validates PKCE code_challenge_method (must be S256 if provided)
  4. Stores state token with PKCE parameters in Redis (5 minutes TTL)
  5. Redirects to login page with OAuth parameters

Arguments

  • realm_id - Realm identifier
  • params - OAuth query parameters (client_id, redirect_uri, state, response_type, code_challenge, code_challenge_method)

Returns

  • 302 redirect to login page with OAuth parameters

Errors

  • 400 - Invalid parameters (missing client_id, redirect_uri, state, or code_challenge)
  • 400 - Invalid response_type (must be "code")
  • 400 - Unsupported code_challenge_method (must be "S256")
  • 404 - Client not found
  • 403 - Client app is disabled
  • 400 - Redirect URI not in whitelist

Path Parameters

realmId*string

Realm ID

Query Parameters

client_id*string

OAuth Client ID

redirect_uri*string

Redirect URI (must be in whitelist, exact match)

state*string

State token (CSRF protection)

response_type*string

Response type (must be 'code')

code_challenge*string

PKCE code challenge (SHA256 + Base64url)

code_challenge_method?string

PKCE method (must be 'S256' if provided, defaults to S256)

scope?string

Space-delimited scope tokens; presence of the literal 'openid' token triggers id_token issuance, other tokens are not interpreted. The built-in MCP client accepts only the four mcp:*:read scopes (absent defaults to mcp:profile:read)

nonce?string

OIDC nonce, echoed into the id_token nonce claim when openid is requested

resource?string

RFC 8707 resource indicator; required on (and only valid for) the built-in MCP client, where it must equal the realm's canonical {origin}/mcp/{realmId} URI

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/oauth/string/authorize?client_id=string&redirect_uri=string&state=string&response_type=string&code_challenge=string"
Empty
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}
{  "code": "string",  "details": null,  "message": "string",  "requestId": "string",  "status": 0}