Authentication

Two credentials, one rule: the credential identifies an account, and every quota and every row it can reach belongs to that account.

You are	Use	Why
Writing code that reads your own smry data	Personal API key	One header, no flow, works unattended.
Building software other people sign in to	OAuth with PKCE	Each user grants access to their own account, and can revoke it.

Personal API keys

Create one in the Developer console. Free accounts can hold two active keys; Patron holds five and Pro holds twenty.

Authorization: Bearer smry_your_key

X-API-Key: smry_your_key

Both are equivalent. Use Authorization: Bearer unless a client library insists on the other.

A key grants full access to the owner’s private library, reading history, and feeds. Never put one in a query string, in client-side code, in logs, or anywhere article content could reach it. Never send it to a publisher URL.

Key lifecycle

Create one key per client or deployment

Then a compromised integration can be revoked on its own.

Copy the secret immediately

smry stores only a verifier and cannot show the secret again.

Keep it in a secret manager

Not in source, not in commit history, not in a screenshot.

Revoke anything unused or exposed

Revocation takes effect on the next request.

Keys can expire, and entitlement is rechecked on every request. Holding more keys does not raise any quota — limits are per account, not per key.

OAuth

Interactive clients discover OAuth at https://api.smry.ai/.well-known/oauth-protected-resource, register dynamically when needed, and run Authorization Code with PKCE. The user must approve access before your client receives a token. Two scopes exist, and an operation declares exactly one:

Scope	Grants	Declared by
`smry:read`	Read the user’s library, history, feeds, and any public URL.	The 20 read-only operations.
`smry:write`	Everything in `smry:read`, plus saving, editing, deleting, following, and monitoring.	The 17 mutating operations, and all MCP access.

Each endpoint page in the API Reference names the scope it requires. Request the narrowest one your client actually needs.

The hosted MCP server requires smry:write, because tool discovery exposes mutating tools. See Connect an agent.

What these credentials do not authorize

Personal keys and OAuth tokens authorize /v1/* and /mcp only. They are not browser sessions: they do not work against smry’s internal /api/* paths. The reverse also holds — a signed-in browser session or extension credential does not authorize /v1/*.

Handling failures

response = httpx.post(url, headers=headers, json=body)

if response.status_code == 401:
    # The credential is wrong, expired, or revoked. Load the right one.
    # Do not retry with the same key.
    raise CredentialError(response.json()["code"])

if response.status_code == 403:
    # The token lacks the required scope. Ask for consent again, or stop cleanly.
    raise PermissionError(response.json()["error"])

if response.status_code == 429:
    # Honour the server's timing.
    time.sleep(int(response.headers.get("Retry-After", "60")))

Status	Meaning	What to do
`401`	Missing, malformed, expired, or revoked credential.	Load the correct secret. Never loop on the same one.
`403`	The token lacks the required scope. It is the only cause: `insufficient_scope` is the only `403` code.	Re-consent for the scope named in `requiredScope`, or stop.
`429`	An account quota was reached.	Wait `Retry-After` seconds. See Rate limits.
`503`	Authentication or another dependency is briefly unavailable.	Retry with exponential backoff and jitter.

Every one of those responses carries the same envelope — error and code, and sometimes hint or retryAfter. Branch on code. Full table in Errors.

Quickstart

Make the first authenticated request.

Rate limits

What a key is allowed to do per minute and per day.

Get started

Work with the API

Patterns

Reference

Authentication

Personal API keys

Key lifecycle

OAuth

What these credentials do not authorize

Handling failures

Next

Quickstart

Rate limits

​Personal API keys

​Key lifecycle

​OAuth

​What these credentials do not authorize

​Handling failures

​Next

Quickstart

Rate limits

Personal API keys

Key lifecycle

OAuth

What these credentials do not authorize

Handling failures

Next