# Usable agent authentication

Protocol compatibility: auth.md b53c9edfbfeea679b617727ebca9ba436bade794

Usable accepts trusted ID-JAG identity assertions with a verified email for an existing Usable account, and service-assisted email claims. Anonymous, phone-only, and just-in-time account provisioning are not supported. Never send credentials to a host other than `https://usable.dev`.

## Discover

Read `https://usable.dev/.well-known/oauth-authorization-server`. Its `agent_auth` member is the machine-readable source of endpoint URLs and supported identity types.

## Register an identity

`POST /agent/identity` with JSON and `Content-Type: application/json`.

- Existing provider identity: `{"type":"identity_assertion","assertion_type":"urn:ietf:params:oauth:token-type:id-jag","assertion":"<ID-JAG>"}`
- Account claim: `{"type":"service_auth","login_hint":"person@example.com"}`

For service-assisted registration, start this request before sending the user to a generic signup page. Give the user `claim.verification_uri`; that page lets them create an account or sign in, accept required terms, review access, and approve the agent in one browser journey.

Follow `claim.verification_uri` when the response requires human confirmation. Do not disclose the user code anywhere except that Usable page. Poll while the user completes the browser flow.

If the short user-code window expires while the claim token remains valid, renew it at `POST /agent/identity/claim` with `{"claim_token":"<token>","email":"person@example.com"}`.

## Exchange credentials

Exchange an accepted assertion at `POST /oauth2/token` using `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` and `assertion=<JWT>`.

Poll a pending claim using `grant_type=urn:workos:agent-auth:grant-type:claim` and `claim_token=<token>`. Honor the returned polling interval and the `authorization_pending` and `slow_down` errors.

## Revoke and events

Revoke a credential at `POST /oauth2/revoke`. Trusted identity providers may send signed Security Event Tokens to `POST /agent/event/notify`.

Access tokens are bearer secrets. Store them securely, never log them, and revoke them when no longer needed.