# auth.md

You are an agent. Sequenzy supports agentic registration for the Sequenzy API and MCP server through the user-claimed `service_auth` flow: discover, register with the user's email, ask the user to confirm the code in a Sequenzy-owned browser page, poll for an access token, then call the API with a bearer credential.

Resource server: `https://api.sequenzy.com`
Authorization server: `https://www.sequenzy.com`

## Step 1 - Discover

Fetch Protected Resource Metadata first. If a 401 response includes `WWW-Authenticate: Bearer resource_metadata="..."`, use that URL. Otherwise use:

```http
GET https://api.sequenzy.com/.well-known/oauth-protected-resource
```

Response fields to read: `resource`, `resource_name`, `resource_logo_uri`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`.

Then fetch OAuth Authorization Server metadata:

```http
GET https://www.sequenzy.com/.well-known/oauth-authorization-server
```

Read `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and the `agent_auth` block. Prefer `service_auth` for new integrations; the `user_claimed` fields remain available for older device-code clients:

```json
{
  "skill": "https://www.sequenzy.com/auth.md",
  "identity_endpoint": "https://www.sequenzy.com/agent/identity",
  "claim_endpoint": "https://www.sequenzy.com/agent/identity/claim",
  "events_endpoint": "https://www.sequenzy.com/agent/event/notify",
  "register_uri": "https://api.sequenzy.com/api/device-auth/initiate",
  "claim_uri": "https://www.sequenzy.com/setup/auth",
  "revocation_uri": "https://www.sequenzy.com/api/oauth/revoke",
  "identity_types_supported": [
    "service_auth",
    "user_claimed"
  ],
  "identity_assertion": {
    "assertion_types_supported": []
  },
  "service_auth": {
    "credential_types_supported": [
      "api_key"
    ],
    "claim_grant_type": "urn:workos:agent-auth:grant-type:claim",
    "credential_transport": "bearer_header"
  },
  "user_claimed": {
    "flow": "device_code",
    "credential_types_supported": [
      "api_key"
    ],
    "verification_uri": "https://www.sequenzy.com/setup/auth",
    "poll_uri": "https://api.sequenzy.com/api/device-auth/poll",
    "credential_transport": "bearer_header"
  },
  "events_supported": []
}
```

## Step 2 - Pick a method

Sequenzy currently prefers `service_auth`.

- Use `service_auth` when you have the user's Sequenzy account email.
- Existing device-code clients may continue to use `user_claimed`.
- Do not use `anonymous`; Sequenzy returns `anonymous_not_enabled`.
- Do not use `identity_assertion`; Sequenzy does not currently accept ID-JAG assertions. Supported ID-JAG assertion types: `urn:ietf:params:oauth:token-type:id-jag` is not enabled.

Requested scope: `mcp`
Credential transport: `Authorization: Bearer <access_token>`

## Current limitations

Sequenzy is not fully agent-friendly yet. This auth.md file helps agents discover registration and obtain a user-approved bearer credential, and MCP/CLI cover many common email workflows. Some setup, billing, destructive account actions, advanced configuration, and final send decisions may still require dashboard use or explicit human review.

## Step 3 - Register

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

{
  "type": "service_auth",
  "login_hint": "user@example.com"
}
```

Success response:

```json
{
  "registration_id": "reg_...",
  "registration_type": "service_auth",
  "claim_url": "https://www.sequenzy.com/agent/identity/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-05-21T17:31:25.994Z",
  "post_claim_scopes": ["mcp"],
    "claim": {
    "user_code": "123456",
    "expires_in": 900,
    "verification_uri": "https://www.sequenzy.com/setup/auth",
    "interval": 5
  }
}
```

No `identity_assertion` is issued. The user must complete the claim ceremony before the agent can receive a bearer credential.

## Step 4 - Claim ceremony

Surface `claim.verification_uri` and `claim.user_code` to the user in one message. The user opens the link, signs in to Sequenzy as `login_hint`, reviews the request, and approves it in Sequenzy. The code is entered on the Sequenzy page, not back into the agent.

Poll the token endpoint with the claim grant no faster than `claim.interval` seconds:

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

grant_type=urn:workos:agent-auth:grant-type:claim
&claim_token=<claim_token>
```

While waiting:

```json
{ "error": "authorization_pending" }
```

On success:

```json
{
  "access_token": "seq_user_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp"
}
```

## Step 5 - Use the access token

```http
Authorization: Bearer <access_token>
```

Full API reference: https://docs.sequenzy.com/api-reference/introduction

## Errors

| Code | Where | What to do |
| --- | --- | --- |
| `invalid_request` | `/agent/identity`, `/agent/identity/claim`, `/api/oauth/token` | Fix missing or malformed fields. |
| `anonymous_not_enabled` | `/agent/identity` | Use `service_auth`. |
| `identity_assertion_not_enabled` | `/agent/identity` | Use `service_auth`; ID-JAG registration is not enabled. |
| `authorization_pending` | `/api/oauth/token` claim grant | Wait `interval` seconds and poll again. |
| `access_denied` | `/api/oauth/token` claim grant | The user denied the request. Stop unless the user asks to restart. |
| `expired_token` | `/api/oauth/token` claim grant | Restart registration. |
| `unsupported_grant_type` | `/api/oauth/token` | Use the claim grant shown above. |

## Revocation

Revoke a bearer credential with the OAuth revocation endpoint:

```http
POST https://www.sequenzy.com/api/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>
&token_type_hint=access_token
```

The revocation endpoint is idempotent and returns 200 for unknown tokens.