# smry authentication for agents

## Discover

The public r.smry.ai reader uses `agent_auth` type `anonymous`. It requires
no registration, claim, login, cookie, API key, or delegated user permission.
Call `GET https://r.smry.ai/api/v1/read?url=<public-url>` directly.

## Pick a method

Choose anonymous public reading for source retrieval. When the user explicitly
asks to access their private smry library, history, notes, highlights, feeds,
files, or monitors, prefer OAuth for an interactive agent and use a personal
`smry_` key only for a local or unattended client that can protect it.

## Register

Anonymous reader calls do not register. For private account tools, first fetch
https://api.smry.ai/.well-known/oauth-protected-resource (or the path-specific
`/mcp` metadata). Follow its authorization server to
https://clerk.smry.ai/.well-known/oauth-authorization-server. Interactive
clients may dynamically register at the advertised registration endpoint. Use
Authorization Code with PKCE and request the minimum advertised scope:
`smry:read` for read-only Developer API operations or `smry:write` for
mutations and MCP. A local client may instead ask the user to create a revocable
personal key at https://smry.ai/mcp-api-cli?view=keys.

The canonical OAuth endpoint inventory is:

- `register_uri`: https://clerk.smry.ai/oauth/register
- `authorization_uri`: https://clerk.smry.ai/oauth/authorize
- `token_uri`: https://clerk.smry.ai/oauth/token
- `revocation_uri`: https://clerk.smry.ai/oauth/token/revoke

The canonical machine-readable registration template is:

```json
{
  "agent_auth": {
    "register_uri": "https://clerk.smry.ai/oauth/register",
    "identity_types_supported": ["anonymous"],
    "anonymous": {
      "credential_types_supported": ["oauth2"]
    },
    "skill": "https://r.smry.ai/auth.md"
  }
}
```

Here, `anonymous` describes dynamic client registration without a separate
client identity assertion. It does not make private smry account data public:
the user must still complete Authorization Code with PKCE and approve scopes.

These are standard OAuth and dynamic-client-registration endpoints. smry does
not advertise a separate auth.md claim ceremony; user approval happens in the
OAuth authorization flow.

## Claim

There is no anonymous claim step and no `identity_assertion` or `id-jag`
exchange for the public reader. OAuth consent delegates only the approved
scopes and can be revoked by the user. A personal key represents the smry
account that created it; possession is not permission to share or persist it
insecurely.

## Use the credential

Send an OAuth access token or personal key only to https://api.smry.ai as
`Authorization: Bearer <credential>`. Store personal keys in a protected
environment variable such as `SMRY_API_KEY`; OAuth clients must use PKCE and
protect refresh tokens. Never send either credential to r.smry.ai, include it
in a source URL, or commit it to a repository.

## Errors

A public reader 429 includes `Retry-After`. A private API 401 response includes
an OAuth `WWW-Authenticate` discovery challenge and means the credential is
absent, invalid, expired, or revoked. A 403 with `insufficient_scope` means
the user must explicitly approve the required scope; other 403 responses can
indicate an ineligible plan or owner boundary and must not be worked around.

## Revocation

Revoke OAuth grants from the user's connected-app settings and revoke personal
keys from https://smry.ai/mcp-api-cli?view=keys. Anonymous reader access has
no credential to revoke. The canonical installation and MCP setup instructions
live at https://smry.ai/agent-setup/prompt.md.