# auth.md

Samva is a developer email API for product teams. Agents can integrate Samva through
server-side API keys, the `samva` CLI, or the hosted MCP server at
`https://mcp.samva.app/mcp`.

This file is the agent-facing authentication guide. It is intentionally scoped to
the auth surfaces Samva supports today. WorkOS auth.md registration endpoints are
not advertised until the service-auth registration flow is live.

## Step 1 — Discover

For live MCP tool execution, start with the protected resource metadata:

```http
GET https://mcp.samva.app/.well-known/oauth-protected-resource
```

Unauthenticated MCP requests return a `401` with:

```http
WWW-Authenticate: Bearer resource_metadata="https://mcp.samva.app/.well-known/oauth-protected-resource"
```

The metadata points to Samva's OAuth Authorization Server. OAuth-capable clients
follow that document automatically.

## Step 2 — Pick a method

Use the credential that matches who is acting:

| Method | Best for | Org scope |
| --- | --- | --- |
| API key | Servers, CI, unattended agents | Bound to one organization |
| CLI OAuth login | A human or coding agent working in a terminal | User session plus active org |
| Hosted MCP OAuth | OAuth-capable MCP clients | Access token bound to one organization |

Use API keys for unattended production automations. Use OAuth when a human is
present to approve access or when the agent needs MCP tool discovery.

## Step 3 — Register

Current production setup does not support agent-initiated WorkOS auth.md
registration. Create credentials through one of these supported paths:

### API key

Create a key in the dashboard under **Developers → API Keys**. Send it as:

```http
X-API-Key: sk_sm_...
```

### CLI login

```bash
samva login
samva org use <org-slug>
```

The CLI uses an OAuth 2.0 device flow and sends the resulting bearer token with
the active organization.

### Hosted MCP

For API-key auth:

```json
{
  "mcpServers": {
    "samva": {
      "type": "http",
      "url": "https://mcp.samva.app/mcp",
      "headers": { "X-API-Key": "sk_sm_..." }
    }
  }
}
```

For an OAuth-capable MCP client, omit headers and use the same URL. The client
discovers the Authorization Server through the protected-resource metadata.

## Step 4 — Claim ceremony

Samva does not currently expose an auth.md claim ceremony. When this launches,
this file and the Authorization Server metadata will advertise the supported
`agent_auth` identity types and endpoints.

## References

- Agent integration guide: https://samva.app/AGENTS.md
- Full docs: https://samva.app/docs
- Hosted MCP: https://mcp.samva.app/mcp
- Agent skill index: https://samva.app/.well-known/agent-skills/index.json