# 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`.

## Client capability preflight

This document describes a protocol; it does not grant a chat HTTP actions, permission to execute remote instructions, secure storage, or a client-configuration surface. An ordinary text chat without the capabilities below is unsupported.

Before requesting `login_hint` or creating a claim, verify that the runtime can:

- Use an installed, allowlisted Usable connector or explicit operator authorization for arbitrary HTTPS GET and POST actions restricted to the exact endpoints declared in `agent_auth`.
- Require every endpoint and returned verification URI to have an origin exactly `https://usable.dev`; reject redirects, URL userinfo, and other schemes, ports, or hosts.
- Poll at the returned interval and handle `authorization_pending`, `slow_down`, expiry, and rejection.
- Store `claim_token` immediately and the access token after approval in an approved secret store outside chat and logs.
- Configure a Usable MCP or API client, prove an authenticated read, and revoke the credential.
- Provide a trusted, non-transcript human handoff that opens the exact verification URI and enters `user_code` only on `https://usable.dev`.

Stop before requesting `login_hint` or creating a claim if any capability is missing, and explain which capability is unavailable. A text-only chat is unsupported even if it can POST. Fetching this document does not authorize bypassing client security policy.

## 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.

Do not claim registration started unless the POST succeeds and returns the required claim fields. No successful POST means no approval URL exists. Never construct, guess, repair, persist, rewrite, or forward an approval URL.

Store `claim_token` immediately. Treat the exact returned `claim.verification_uri` as short-lived sensitive handoff material: open it only for the approving user through the trusted non-transcript handoff. Confirm its origin is exactly `https://usable.dev`, and enter `user_code` only on that Usable page. Never place `claim_token`, `user_code`, `claim.verification_uri`, or the access token in chat or logs. 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.