# auth.md

You are an agent. Menciona supports **agentic registration**: discover →
subscribe (register + pay in one call) → receive a long-lived API key → call
the API/MCP → revoke. This document tells you how to authenticate with the
Menciona API and MCP server. It complements the machine-readable discovery
metadata:

- OAuth Authorization Server metadata (RFC 8414): <https://api.menciona.ai/.well-known/oauth-authorization-server>
- OAuth Protected Resource metadata (RFC 9728): <https://api.menciona.ai/.well-known/oauth-protected-resource>
- MCP Server Card: <https://menciona.ai/.well-known/mcp/server-card.json>

## What you can access

| Resource | URL | Auth |
| --- | --- | --- |
| MCP server (StreamableHTTP) | `https://api.menciona.ai/mcp` | Required |

The MCP server speaks **plain JSON-RPC 2.0 over ordinary HTTPS** — "StreamableHTTP"
is just the transport name. A normal `curl` POST works; you do **not** need an MCP
client library, a WebSocket, or a persistent connection. See the copy-paste handshake
at <https://menciona.ai/en/mcp/>.

An **active Menciona subscription** is required to call the MCP server.
Unauthenticated requests receive `401` with a
`WWW-Authenticate: Bearer resource_metadata="..."` header pointing at the
protected-resource metadata.

## Option A - OAuth 2.1 (recommended for agents)

The authorization server is `https://api.menciona.ai`. It supports Dynamic
Client Registration, so agents can self-register without manual setup.

| Endpoint | URL |
| --- | --- |
| Registration | `https://api.menciona.ai/register` |
| Authorization | `https://api.menciona.ai/authorize` |
| Token | `https://api.menciona.ai/token` |
| Revocation | `https://api.menciona.ai/revoke` |

- **Grant types:** `authorization_code`, `refresh_token`
- **PKCE:** required (`code_challenge_methods_supported: ["S256"]`)
- **Client auth:** public clients (`token_endpoint_auth_methods_supported: ["none"]`)
- **Scopes:** `read`, `read_write`, `offline_access`

**Flow**

1. `POST /register` to obtain a `client_id` (dynamic registration).
2. Redirect the user to `/authorize` with `response_type=code`, your
   `client_id`, `redirect_uri`, `scope`, and a PKCE `code_challenge` (S256).
3. Exchange the returned `code` at `/token` with your `code_verifier` to
   receive an access token (and a refresh token when `offline_access` is
   requested).
4. Call the API/MCP with `Authorization: Bearer <access_token>`.

## Option B - API key

Users can issue a personal API key in the Menciona dashboard. Send it as a
bearer token: `Authorization: Bearer menciona_...`. API keys carry the
workspace's scope (`read` or `read_write`).

## Notes

- Tokens are validated per request; workspace membership and subscription
  status are re-checked, so access can be revoked immediately.
- Start here to create an account or issue a key: <https://app.menciona.ai>

## Option C - Agent registration via ACP checkout (register + pay)

Any agent that can present a credit card can subscribe autonomously — no
pre-shared key, no Stripe account of its own. Checkout calls are **public**
(no request signing). Abuse is handled by Stripe Radar + rate limits.

### 1. Discover

`GET https://app.menciona.ai/api/acp/feed` returns purchasable plans (each with a
`plan_price_id`) and a top-level `publishable_key` (a Stripe `pk_…`, safe to use
client-side).

Machine-readable discovery metadata:
- `https://api.menciona.ai/.well-known/oauth-authorization-server` — look for the `agent_auth`
  block pointing here.
- `https://menciona.ai/.well-known/api-catalog` — ACP surface anchor.
- `https://menciona.ai/.well-known/mcp/server-card.json` — `x_agentic_commerce` capability.

### 2. Tokenize the card

Turn the card into a reusable PaymentMethod **with Stripe**, using the
publishable key from the feed. The raw card goes to Stripe, never to Menciona.
`allow_redisplay=always` is REQUIRED so the card can be reused for renewals.

```bash
curl https://api.stripe.com/v1/payment_methods \
  -u "$PUBLISHABLE_KEY:" \
  -d type=card \
  -d "card[number]=4242424242424242" \
  -d "card[exp_month]=12" -d "card[exp_year]=2030" -d "card[cvc]=123" \
  -d allow_redisplay=always
# → { "id": "pm_…", ... }
```

### 3. Open a checkout session

```http
POST https://app.menciona.ai/api/acp/checkout_sessions
Content-Type: application/json

{ "plan_price_id": "<from the feed>" }
```

Returns a `CheckoutSession` with `id` (`cs_…`).

### 4. Complete (register + pay — atomic)

```http
POST https://app.menciona.ai/api/acp/checkout_sessions/{id}/complete
Content-Type: application/json

{
  "buyer":        { "email": "agent@example.com" },
  "payment_data": { "token": "pm_…", "provider": "stripe" },
  "consent":      { "recurring": true }
}
```

Success returns the long-lived API key:

```json
{ "workspace_id": "…", "subscription_id": "sub_…", "access_token": "menciona_…", "token_type": "Bearer" }
```

> Cards that require 3D Secure (mostly EU/UK) cannot complete headlessly — the
> call returns `requires_3ds`; retry with a different card.
>
> An email that already has a Menciona workspace returns `409 requires_sign_in`
> ("Email already registered"). Checkout registers a *new* account only — use a
> different email for a fresh anonymous workspace, or sign in to the existing one
> at <https://app.menciona.ai>.

### 5. Use

Add the key as a bearer token on every request:

```http
Authorization: Bearer menciona_…
```

Use the key with the MCP server (`https://api.menciona.ai/mcp`). It is **plain
JSON-RPC 2.0 over HTTPS — a normal `curl` POST, no MCP client or WebSocket needed**:
send `initialize`, then `tools/list`, then `tools/call`. Copy-paste handshake:
<https://menciona.ai/en/mcp/>.

### 6. Revoke

Delete the API key via the Menciona dashboard (<https://app.menciona.ai>) or the API. The key
is invalidated immediately on all subsequent requests.

## After you subscribe

Read how monitoring and audits run (cadence, quota-gating, polling):
<https://menciona.ai/skills/how-monitoring-and-audits-work.md>. Plan quotas:
<https://menciona.ai/skills/quotas-and-limits.md>. Found a bug? Use the
`feedback.submit` MCP tool — see
<https://menciona.ai/skills/report-an-issue.md>.