# Recoup agent authentication

Use this flow to read an existing Recoup account's personal artists, social profiles, and chat list.
The account holder must sign in to Recoup, enter the code displayed by the agent, and explicitly approve.
The service_auth flow grants only mcp:read for 60 minutes. Organization workspaces and write tools are excluded.
For broader permissions, use the existing OAuth authorization-code flow with PKCE and explicit consent.

## Discovery
- [Protected resource metadata](https://api.recoupable.dev/.well-known/oauth-protected-resource)
- [Authorization server metadata](https://api.recoupable.dev/api/oauth/.well-known/openid-configuration)
- [Connected agents](https://app.recoupable.dev/oauth/connections)

## Register
POST https://api.recoupable.dev/api/oauth/agent/identity with application/json:
`{"type":"service_auth","login_hint":"the account holder's verified email"}`

This returns registration_id, claim_token, claim_token_expires, and a claim block with user_code,
verification_uri, expires_in (600 seconds), and interval (5 seconds). It returns no account credential.
Show the code and link to the account holder. Never collect their password or complete the consent for them.
Keep claim_token private; do not include it in the verification URL. A rejected or expired ceremony needs a new registration.

## Receive a token
POST https://api.recoupable.dev/api/oauth/token with application/x-www-form-urlencoded:
`grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>`

Poll no faster than interval. authorization_pending means wait. On slow_down, add five seconds
to the interval (up to sixty). access_denied and expired_token stop the attempt.
Approval returns access_token, token_type Bearer, expires_in (at most 300), scope mcp:read,
identity_assertion, and assertion_expires. No refresh_token is issued.

Use Authorization: Bearer <access_token> only at https://api.recoupable.dev/mcp.
To renew within the approved 60 minutes, POST the same token endpoint:
`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>&resource=https://api.recoupable.dev/mcp`
The assertion can be re-exchanged until assertion_expires. Scope and resource cannot be widened.
An expired session requires new account-holder consent.

## Revoke
POST https://api.recoupable.dev/api/oauth/token/revocation with application/x-www-form-urlencoded:
`token=<access_token>&token_type_hint=access_token`
This invalidates that access token. The account holder disconnects the registration in Connected agents
to invalidate all its tokens and future assertion exchanges.

Only service_auth is supported here. No anonymous access, external-provider assertions, or security-event
receiver is advertised. Keep credentials out of prompts, logs, URLs, and tool results.