OAuth endpoints

POST/initiateOAuth

Body

Name

Type

Required

Description

appId

string

required

ID of the App requiring authorization

userId

string

required

Your end-user identifier

clientRedirectUri

string

required

Must be pre-registered on AI Client

Response

{
  "authorizationUrl": "https://provider.com/oauth/authorize?...",
  "state": "opaque-token-with-10min-ttl",
  "expires_at": "2026-05-05T14:35:00Z"
}

GET/handleOAuthCallback

Note

You do NOT call this endpoint. The provider redirects to it. The platform finishes the exchange, encrypts tokens with KMS, and bounces the user to your clientRedirectUri with ?status=success or ?status=error&reason=....

Errors

state_invalid — TTL expired or replay attempt.
code_exchange_failed — provider rejected the auth code.
redirect_uri_mismatch — clientRedirectUri not pre-registered on AI Client.