# Trusted third-party tokens

If your users already sign in somewhere else (your own identity service, another auth provider, a partner), OhAuthCat can accept that issuer's JWTs and return an OhAuthCat profile for them, in the spirit of OAuth token exchange (RFC 8693). This is a Business plan feature.

## Trust an issuer

`POST /v1/trusted_issuers` (or `ohauthcat trusted-issuers create`) with:

| Field             | Meaning                                                            |
| ----------------- | ------------------------------------------------------------------ |
| `issuer`          | The exact `iss` value                                              |
| `jwks_url`        | Where the issuer publishes its public keys                         |
| `audiences`       | 1 to 10 accepted `aud` values                                      |
| `algorithms`      | Allowed algorithms: `RS256`, `ES256` and/or `EdDSA`                |
| `skew_seconds`    | Allowed clock skew, 0 to 300 (default 60)                          |
| `claim_mapping`   | Which claims hold the subject, email, email verification and names |
| `organization_id` | The organization every exchanged user belongs to (optional)        |
| `jit_by_domain`   | Instead, place users by a verified domain of a verified email      |

## Exchange a token

`POST /v1/sso/token_exchange` with the token (scope `sso:exchange`) returns the profile.

OhAuthCat checks the algorithm against the issuer's list before touching any key, refuses tokens that carry their own key or key URL (`jku`, `x5u`, `jwk`, `x5c`) or a `crit` header, takes keys only from the registered JWKS, and requires an exact issuer and audience, an `exp`, a lifetime of at most 24 hours and plausible `nbf` and `iat`. Each `jti` is accepted once. Failures answer [`trusted_token_invalid`](/errors/trusted_token_invalid/) or [`trusted_token_replayed`](/errors/trusted_token_replayed/).

The exchange returns the profile and stores it (audit `trusted_token.exchanged`). Exchanged identities are not end users: they never count toward monthly active users and are not billable.

## Get an OhAuthCat access token

Add `client_id` (a publishable key of the environment) to the exchange and the answer also carries `access_token`, `issued_token_type`, `token_type` and `expires_in`. The token is an ES256 JWT signed with the environment's key ring (JWKS on the login host), issued by `https://login.ohauthcat.com`, with `aud` = the client_id, `sub` = the stored profile's `tprof_…` ID, and the claims `ext_iss`, `ext_sub`, `trusted_issuer_id`, `env`, `org_id` (when the profile belongs to an organization) and `jti`. It lives 10 minutes by default (configurable from 1 minute to 1 hour).
