# Identity

> The doors that give one of your users a token for a loop, and your own OpenID issuer

A user token lets one of your users reach their own runs of a loop. The loop's identity scheme decides which door mints it; the [API Overview](/docs/api/overview.md) says how a token is sent.

## Doors

| Route | For | Body |
|---|---|---|
| `POST /api/loops/{publicId}/visitors` | An **anonymous** visitor | `previous_token` to renew, `ancestor_origin` for an embed |
| `POST /api/loops/{publicId}/identities` | A user **your system vouches for** | `assertion`: a compact HS256 JWT your server signs with the loop's secret; its `sub` becomes the run's subject. On a loop whose scheme is `oidc`, `assertion` is instead an id token from your own OpenID issuer (see [Your own OpenID issuer](#your-own-openid-issuer)) |
| `POST /api/loops/{publicId}/door` | Asking whether a caller would be admitted, without minting anything | The same body as the door it checks |

Each door answers a user token (`token`, `expires_at`, `subject`). An assertion can be exchanged
once. An owner reads the loop's secret on its **Keys** tab, under **Signing secret**, and rotates it
there. Rotating refuses assertions signed with the old one at once.

## Your own OpenID issuer

A loop whose identity scheme is `oidc` names an **issuer** and a **client id**. Send the id token
your issuer gave the user as `assertion` on `/identities`. The token must be signed `RS256` or
`ES256` with a key the issuer publishes, its `iss` must be the issuer, its `aud` must name the
client id, and its `sub` becomes the run's subject. A refusal names the check that failed.
