# auth.md — CryptoStruct

How AI agents authenticate against https://cryptostruct.com (and its MCP server).

## TL;DR

- **Most things need NO auth.** The public market-data APIs (see [/llms.txt](https://cryptostruct.com/llms.txt))
  and the MCP free + commerce tiers (catalog, stats, price quotes, Stripe checkout hand-off)
  are fully keyless — no signup, no API key.
- **Sign-in is OAuth 2.0** (authorization code + PKCE, Dynamic Client Registration) and only
  unlocks account tools (your orders/files/credits) and Premium features.
- Tokens are sent as `Authorization: Bearer …` headers. Nothing else is accepted.

## Discovery (start here)

Read the live documents — do not hardcode endpoints from this file:

- Protected-resource metadata (RFC 9728):
  [/.well-known/oauth-protected-resource](https://cryptostruct.com/.well-known/oauth-protected-resource)
  · [/mcp](https://cryptostruct.com/.well-known/oauth-protected-resource/mcp)
  · [/mcp/auth](https://cryptostruct.com/.well-known/oauth-protected-resource/mcp/auth)
- Authorization-server metadata (RFC 8414):
  [/.well-known/oauth-authorization-server](https://cryptostruct.com/.well-known/oauth-authorization-server)
  — carries `registration_endpoint`, `authorization_endpoint`, `token_endpoint`,
  `revocation_endpoint`, `jwks_uri`.
- MCP server card: [/.well-known/mcp/server-card.json](https://cryptostruct.com/.well-known/mcp/server-card.json)

## Register & sign in (the flow that works today)

1. POST a tokenless MCP request to `https://cryptostruct.com/mcp/auth` → `401` with a
   `WWW-Authenticate` header pointing at the protected-resource metadata.
2. Follow it to the authorization server, register a client via
   **Dynamic Client Registration** (RFC 7591, public client) at the
   `registration_endpoint` from the RFC 8414 document.
3. Run the **authorization code + PKCE** flow. The user consents in their browser
   (scopes: `openid profile email`). There is no service-account or assertion flow.
4. Call `https://cryptostruct.com/mcp/auth` (or `/mcp`) with the access token as a Bearer header.

MCP clients like claude.ai, Claude Code (`claude mcp add --transport http cryptostruct https://cryptostruct.com/mcp/auth`)
and Cursor do all of this automatically when pointed at `https://cryptostruct.com/mcp/auth`.

## Tiers & quotas

- **free / commerce** — keyless. Weighted tool budget 120 units/min per caller.
- **account** — requires sign-in; gated tools answer `AUTH_REQUIRED` with instructions.
- **premium** — requires the CryptoStruct Premium subscription (€20/month, purchased on the
  website); gated tools/params answer `PREMIUM_REQUIRED` with an upgrade URL. Budget
  600 units/min. Details: [/docs/mcp](https://cryptostruct.com/docs/mcp).

## Revocation

Revoke tokens at the `revocation_endpoint` from the RFC 8414 metadata, or sign the agent
out of the account. Server-side verification caches mean revocation takes effect within
~7 minutes.

## agent_auth mapping

The `agent_auth` block in our [RFC 8414 metadata](https://cryptostruct.com/.well-known/oauth-authorization-server)
maps this plain OAuth flow into the WorkOS auth.md vocabulary — every URL in it is a live
endpoint:

- `register_uri` — the RFC 7591 Dynamic Client Registration endpoint (expects a standard
  DCR payload, **not** an identity assertion).
- `identity_types_supported: ["anonymous"]` — no identity is needed to register a client.
- `claim_uri` — the OAuth authorization endpoint: the user "claims" (authorizes) the agent
  through the normal browser consent, which yields the tokens.
- `revocation_uri` — RFC 7009 token revocation.

Not supported (deliberately absent): ID-JAG identity assertions, `service_auth`,
verified-email flows and revocation event feeds.