Skip to content
Dashboard
Theme
Theme

Exchange a trusted third-party token for a profile

POST /v1/sso/token_exchange: Exchange a trusted third-party token for a profile.

View Markdown

POST /v1/sso/token_exchange

RFC 8693-style token exchange. The subject token is a JWT from a registered trusted issuer; its signature (RS256, ES256 or EdDSA from the issuer’s JWKS only), iss, aud, exp, nbf and iat are checked, and a jti is accepted once. Claims map to the profile by the issuer’s claim mapping. An organization is attached only when the issuer names one or, with JIT by domain, when the verified email’s domain is a verified domain of an organization. The profile is stored. With client_id (a publishable key of the environment) the answer also carries an OhAuthCat access token (issuer the login host, audience the client_id, sub the profile ID, claims ext_iss and ext_sub, lifetime TRUSTED_TOKEN_EXCHANGE_TTL, 10 minutes by default). Exchanged identities never count toward billable profiles or monthly active users. Business plan and above.

Scope
sso:exchange
Auth
Secret key (sk_…)
Since
1.0
  • OhAuthCat-Version string

    Minor version; defaults to the environment’s pin.

  • grant_type string Required

  • subject_token string Required

    min length 1 · max length 16384

  • subject_token_type string Required

    one of urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token

  • client_id string

    The environment’s publishable key the issued access token is for (its audience).

    max length 256

Errors share one shape; see the error code catalogue.

curl -X POST \
"https://api.ohauthcat.com/v1/sso/token_exchange" \
-H "Authorization: Bearer $OHAUTHCAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token": "sk_test_example",
"subject_token_type": "urn:ietf:params:oauth:token-type:jwt"
}'
Response 200
{
"object": "trusted_token_profile",
"id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"issuer_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"subject": "example_subject",
"email": "jane@acme.com",
"email_verified": true,
"first_name": "Jane",
"last_name": "Doe",
"organization_id": "org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
"expires_at": "2026-01-15T09:30:00Z",
"access_token": "sk_test_example",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 1
}