# auth.md

Agent registration and authentication for [dak.dev](https://dak.dev/).

## Audience

AI agents that need to call dak.dev MCP transports or understand how humans authenticate.

## Human authentication

End users sign in at [https://dak.dev/login](https://dak.dev/login) using Better Auth social providers (Discord, GitHub, Twitter). Session cookies authenticate the browser app. There is no email/password registration.

Discovery documents:

- OAuth Authorization Server: [https://dak.dev/.well-known/oauth-authorization-server](https://dak.dev/.well-known/oauth-authorization-server)
- OpenID Configuration: [https://dak.dev/.well-known/openid-configuration](https://dak.dev/.well-known/openid-configuration)
- Protected Resource: [https://dak.dev/.well-known/oauth-protected-resource](https://dak.dev/.well-known/oauth-protected-resource)

## Registration {#registration}

dak.dev does not offer automated public agent account registration that creates user accounts.

Agents authenticate to MCP endpoints with **pre-provisioned bearer tokens**:

1. A human signs in at /login.
2. For iCloud MCP, the human creates a credential at [https://dak.dev/icloud-mcp](https://dak.dev/icloud-mcp) and copies the bearer token.
3. For admin MCP surfaces (feed, newsletter vibes), the operator configures `MCP_ADMIN_TOKEN` and supplies that token to the agent out of band.

## MCP bearer tokens {#mcp-bearer-tokens}

Send the token as:

```http
Authorization: Bearer <token>
```

| Resource | Endpoint | How to obtain token |
| --- | --- | --- |
| iCloud MCP | https://dak.dev/api/icloud-mcp | Create credential in the signed-in iCloud MCP UI |
| Feed MCP | https://dak.dev/api/feed | Operator-issued `MCP_ADMIN_TOKEN` |
| Newsletter vibes MCP | https://dak.dev/api/newsletter-vibes | Operator-issued `MCP_ADMIN_TOKEN` |

Unauthorized MCP calls receive `401` with a `WWW-Authenticate` challenge when supported by the transport. HTTP failures use `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) with machine-readable `code`, human-readable `detail`, and a `resolution` hint.

## API contract, versions, and limits

The public HTTP contract is version 1. Clients can send `X-Dak-API-Version: 1` to pin their integration; every MCP response echoes that version in `X-Dak-API-Version`. A future breaking version will use a new header value and remain available alongside version 1 for at least 90 days. dak.dev announces a planned retirement with the HTTP `Deprecation` and `Sunset` headers at least 90 days before removing a version.

MCP transports allow 120 requests per client per 60-second window. Responses include the RFC 9331 `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy` headers. A `429` also includes `Retry-After`; wait that many seconds before retrying.

The complete typed contract, including request parameters and all success/error response schemas, is published at [https://dak.dev/.well-known/openapi.json](https://dak.dev/.well-known/openapi.json).

## Scopes

- `mcp` — access to MCP Streamable HTTP transports
- Browser sessions use Better Auth session cookies (not bearer tokens)

## Revocation

- iCloud MCP credentials can be revoked in the iCloud MCP account UI.
- Admin tokens are rotated by changing `MCP_ADMIN_TOKEN` in the deployment environment.

## Related

- API catalog: https://dak.dev/.well-known/api-catalog
- MCP server card: https://dak.dev/.well-known/mcp/server-card.json
- llms.txt: https://dak.dev/llms.txt