Exchange a trusted third-party token for a profile
POST /v1/sso/token_exchange: Exchange a trusted third-party token for a profile.
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
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Request body
Section titled “Request body”grant_typestring Requiredsubject_tokenstring Requiredmin length 1 · max length 16384
subject_token_typestring Requiredone of
urn:,ietf: params: oauth: token-type: jwt urn:ietf: params: oauth: token-type: id_token
The environment’s publishable key the issued access token is for (its audience).client_idstringmax length 256
Responses
Section titled “Responses”- 200 OK TrustedTokenProfile
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
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"}'const response = await fetch("https://api.ohauthcat.com/v1/sso/token_exchange", { method: "POST", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "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" }),});const data = await response.json();import osimport requests
response = requests.post( "https://api.ohauthcat.com/v1/sso/token_exchange", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "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", },)data = response.json(){ "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}