Identity
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 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) |
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.