# Exchange a trusted third-party token for a profile

<div class="api-op" data-api-operation>
<div class="api-op__main">

<p class="api-endpoint"><span class="method method-post">POST</span> <code>/v1/sso/token_exchange</code></p>

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.

<dl class="api-facts"><div><dt>Scope</dt><dd><code>sso:exchange</code></dd></div><div><dt>Auth</dt><dd>Secret key (<code>sk_…</code>)</dd></div><div><dt>Since</dt><dd>1.0</dd></div></dl>

## Headers

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">OhAuthCat-Version</code> <span class="api-field__type">string</span></p>
Minor version; defaults to the environment's pin.
</li>
</ul>

## Request body

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">grant_type</code> <span class="api-field__type">string</span> <span class="api-field__required">Required</span></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">subject_token</code> <span class="api-field__type">string</span> <span class="api-field__required">Required</span></p>

<p class="api-field__chips">min length 1 · max length 16384</p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">subject_token_type</code> <span class="api-field__type">string</span> <span class="api-field__required">Required</span></p>

<p class="api-field__chips">one of <code>urn:ietf:params:oauth:token-type:jwt</code>, <code>urn:ietf:params:oauth:token-type:id_token</code></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">client_id</code> <span class="api-field__type">string</span></p>
The environment's publishable key the issued access token is for (its audience).

<p class="api-field__chips">max length 256</p>
</li>
</ul>

## Responses

<ul class="api-responses">
<li class="api-response"><span class="api-status api-status--ok">200</span> <span>OK <span class="api-field__type">TrustedTokenProfile</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">400</span> <span>Invalid request. Codes: <a href="/errors/parameter_invalid/">parameter_invalid</a>, <a href="/errors/parameter_missing/">parameter_missing</a>, <a href="/errors/version_unsupported/">version_unsupported</a> and resource-specific codes from the catalogue. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">401</span> <span>Codes: <a href="/errors/authentication_required/">authentication_required</a>, <a href="/errors/api_key_invalid/">api_key_invalid</a>. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">403</span> <span>Codes: <a href="/errors/api_key_scope_missing/">api_key_scope_missing</a>, <a href="/errors/ip_not_allowed/">ip_not_allowed</a>, <a href="/errors/plan_limit_reached/">plan_limit_reached</a>. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">429</span> <span>Code: <a href="/errors/rate_limited/">rate_limited</a>. Retry-After is set. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">503</span> <span>Code: <a href="/errors/service_unavailable/">service_unavailable</a>. Retry-After is set; writes are paused. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--neutral">default</span> <span>Any other error, including <a href="/errors/internal_error/">internal_error</a>. Every code is in the error catalogue. <span class="api-field__type">Error</span></span></li>
</ul>

Errors share one shape; see the [error code catalogue](/errors/).

</div>
<div class="api-op__code">

**curl**

```sh wrap
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"
}'
```

**Node**

```javascript wrap
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();
```

**Python**

```python wrap
import os
import 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()
```

```json title="Response 200" wrap
{
  "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
}
```

</div>
</div>
