# TimeZyme auth.md

You are an agent. This page says how to act for a TimeZyme reader when you have no browser of your own: you register with the reader's email, show the reader a link and a 6-digit code, and poll for tokens while the reader signs in on TimeZyme, types the code and presses Allow. TimeZyme sends no email and creates no account for you.

If you can open a browser for the reader, use the standard OAuth 2.1 sign-in instead (authorization code with PKCE), as https://timezyme.com/.well-known/oauth-authorization-server describes.

## Step 1: Discover

- The account MCP server is https://timezyme.com/mcp/account; its protected resource metadata is https://timezyme.com/.well-known/oauth-protected-resource/mcp/account.
- The authorization server metadata, https://timezyme.com/.well-known/oauth-authorization-server, names the endpoints below in `agent_auth` and lists `urn:workos:agent-auth:grant-type:claim` in `grant_types_supported`.

## Step 2: Register

Before you send the reader's email, tell the reader you are connecting to TimeZyme and which scopes you will ask for.

```http
POST https://timezyme.com/agent/identity
Content-Type: application/json

{ "type": "service_auth", "login_hint": "reader@example.com", "agent_name": "My agent", "scope": "zymes:read zymes:ask" }
```

- `login_hint`: the reader's email. Required.
- `agent_name`: optional, at most 64 characters. The reader sees it on the consent page and in Connected apps, marked Not verified, since TimeZyme cannot confirm it.
- `scope`: optional, space separated, from the scopes below. Default `zymes:read`.

The body `{ "type": "identity_assertion", "assertion_type": "verified_email", "assertion": "reader@example.com" }` is the same request.

Reply (200):

```json
{
  "registration_id": "…",
  "registration_type": "service_auth",
  "claim_url": "https://timezyme.com/agent/identity/claim",
  "claim_token": "clm_…",
  "claim_token_expires": "2026-11-16T17:31:25.994Z",
  "post_claim_scopes": ["zymes:read", "zymes:ask"],
  "claim": {
    "user_code": "123456",
    "expires_in": 600,
    "verification_uri": "https://timezyme.com/oauth/authorize?claim_attempt_token=…",
    "interval": 5
  }
}
```

Every well-formed email gets this reply, whether or not it has a TimeZyme account. Hold `claim_token` in memory until Step 4 is over; it is shown once and TimeZyme keeps no copy.

## Step 3: Hand off to the reader

Show the reader `claim.verification_uri` and `claim.user_code` in one message, for example:

> Open this link, sign in to TimeZyme or create an account, type the code 123456 and press Allow.

The code goes on TimeZyme's page, never back to you. Only the TimeZyme account with the email you registered can use the link.

## Step 4: Poll

Every `claim.interval` seconds:

```http
POST https://timezyme.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_…
```

Poll once more after `claim_token_expires`, since an Allow pressed in the code's last seconds is still collected.

| Status | `error` | Meaning | Do |
|---|---|---|---|
| 400 | `authorization_pending` | The reader has not pressed Allow yet. | Poll again. |
| 400 | `access_denied` | The reader pressed Deny. | Stop. |
| 400 | `expired_token` | The code's 10 minutes passed, or TimeZyme cannot find the registration. | Register again. |
| 400 | `invalid_grant` | The claim token does not match, or its tokens were already collected or can no longer be. | Register again. |
| 429 | | Too many requests. | Wait `Retry-After` seconds. |

On success (200), the standard OAuth token response with `client_id` added:

```json
{ "access_token": "…", "token_type": "bearer", "expires_in": 3600, "refresh_token": "…", "scope": "zymes:read zymes:ask", "resource": "https://timezyme.com/mcp/account", "client_id": "…" }
```

`scope` is what the reader allowed, which can differ from what you asked for.

## Step 5: Call TimeZyme

Send `Authorization: Bearer <access_token>` to the account MCP server, https://timezyme.com/mcp/account (Streamable HTTP), or to the A2A agent's `ask-a-zyme` skill at https://timezyme.com/a2a.

## Refresh

When the access token expires, renew it with the standard refresh grant and the `client_id` from Step 4:

```http
POST https://timezyme.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=…&client_id=…
```

`invalid_grant` means the connection has ended: the reader disconnected you in Settings › Security › Connected apps, or it went unused too long. Start again at Step 2.

## Scopes

| Scope | Allows |
|---|---|
| `zymes:read` | Read your Zymes and the Featured Zymes your plan includes. Always granted. |
| `zymes:ask` | Ask Zyme questions. Each answer is charged to your credits. |
| `papers:add` | Add papers to your Saved sources. You still press Process on timezyme.com yourself. |

## Errors

| Where | Status | `error` | Meaning |
|---|---|---|---|
| /agent/identity | 400 | `invalid_request` | The body is not one of the two above, the email is not an email, the name is too long or a scope is unknown. |
| /agent/identity | 400 | `anonymous_not_enabled` | TimeZyme offers no anonymous registration. |
| /agent/identity | 400 | `issuer_not_enabled` | TimeZyme accepts no ID-JAG or other identity assertion. |
| /agent/identity/claim | 400 | `invalid_claim_token` | The claim token or the email does not match a registration. |
| /agent/identity/claim | 409 | `claimed_or_in_flight` | The registration is still live, or the reader has decided. Keep polling. |
| /agent/identity/claim | 410 | `claim_expired` | The registration has expired. Register again. |
| both | 429 | `rate_limited` | Wait `Retry-After` seconds. |

## Limits

- /agent/identity and /agent/identity/claim together: 20 requests a minute from one address.
- /oauth/token: 2,000 requests a minute from one address, polls included.
- A registration and its code last 10 minutes.

## How TimeZyme differs from the Auth.md profile (v0.6.0)

- Tokens are renewed with the standard `refresh_token` grant and the `client_id` the token response carries. TimeZyme issues no `identity_assertion` and takes no JWT-bearer grant.
- A registration lasts only as long as its code, 10 minutes, so /agent/identity/claim never issues a second code.
- `agent_name` and `scope` are TimeZyme's own optional fields.
- The first version's `identity_assertion` body with `verified_email` is the same request as `service_auth`. Its later steps, a code emailed to the reader and read back to you, are not offered.
- Anonymous and ID-JAG registration are not offered.
