# whoistyping.wtf agent authentication
Only the user-claimed service_auth profile is supported. Anonymous and provider ID-JAGs are not supported.
Discover https://whoistyping.wtf/.well-known/oauth-protected-resource and https://whoistyping.wtf/.well-known/oauth-authorization-server.
POST JSON to https://whoistyping.wtf/agent/identity:
{"type":"service_auth","login_hint":"human@example.com","agent_name":"Setup assistant","scopes":["api.read","api.write"]}
Show claim.verification_uri and claim.user_code to the human. Do not enter the code or approve on their behalf.
They sign up/sign in, confirm their email, enter the code, explicitly select an organization and approve or deny the listed scopes.
No credential exists before approval. Claim expires in 600 seconds. Poll no faster than every 5 seconds.
POST form-encoded to https://whoistyping.wtf/oauth2/token:
grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>&resource=https://whoistyping.wtf/api/v1
authorization_pending: keep waiting. slow_down: increase polling interval by 5 seconds (maximum 60).
expired_token or access_denied: stop; obtain fresh explicit human approval with a new registration.
Approved poll returns Bearer access_token, expires_in, scope, identity_assertion and assertion_expires. Keep these private.
Access tokens expire in 1 hour. Assertions expire within 24 hours of approval. There is no refresh_token.
Before assertion expiry, POST form grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https://whoistyping.wtf/api/v1 to exchange it.
Optional scope may only narrow granted permissions; resource must match exactly.
Call https://whoistyping.wtf/api/v1 with Authorization: Bearer <access_token>.
Scopes: api.read (organization/projects/documents/logs/usage), api.write (rename/configure/create projects).
secrets.read permits reading project secrets. It is ALSO required, together with api.write, to set endpoint_url or webhook_format (including at creation), or test a webhook: receivers may receive project credentials.
secrets.rotate permits rotating project secrets. api.destroy permits archiving projects/deleting documents and is ALSO required, together with api.write, to enable auto_delete_on_quota (including at creation).
Tokens cannot manage delegations, other tokens, account security, billing or onboarding. Other organizations remain inaccessible.
POST form token=<access_token> to https://whoistyping.wtf/oauth2/revoke to idempotently revoke only that credential.
The assertion can still issue new credentials. A human owner/admin revokes the entire delegation from Settings → Agent access.
Revocation, membership removal/demotion, unconfirmation/deactivation and organization blocking deny delegated access and assertion exchange.
Protocol: workos/auth.md service_auth profile, revision b53c9edfbfeea679b617727ebca9ba436bade794; no claim of broad agent-client compatibility.