# Postedly auth.md

How AI agents and their clients get credentials for Postedly's MCP server and HTTP API.

## Who this is for

Agents, MCP clients and automations that prepare letters, certified mail, postcards, faxes or handwritten cards for a person. Every credential acts for one person who signed in and approved the connection in their browser. Postedly has no agent self-registration, no permanent API keys and no client-credentials grant. Hosted agents with no callback of their own can use the device code flow below.

## Discovery

- Protected resource metadata (MCP): https://postedly.com/.well-known/oauth-protected-resource/mcp/send
- Protected resource metadata (correspondence-only MCP): https://postedly.com/.well-known/oauth-protected-resource/mcp/correspondence
- Authorization server metadata: https://postedly.com/.well-known/oauth-authorization-server (issuer `https://postedly.com`)
- AI Catalog: https://postedly.com/.well-known/ai-catalog.json
- MCP server cards: https://postedly.com/mcp/send/server-card and https://postedly.com/mcp/correspondence/server-card (earlier format: https://postedly.com/.well-known/mcp/server-card.json)

- Public catalog MCP server card (no credential needed for that endpoint): https://postedly.com/mcp/catalog/server-card

Read endpoints from the metadata rather than hard-coding them.

The public catalog endpoint (POST to /mcp/catalog on postedly.com) needs no credential and never returns a `401`. It lists services and prices a send, accepts no documents or personal data, and cannot create a quote or order. Everything else on this page applies to the authenticated endpoints.

## Get credentials

Choose one way to identify your client. Read the endpoints from the authorization server metadata.

1. **Client ID Metadata Document (preferred).** Host a JSON document at an HTTPS URL you control and use that URL as your `client_id`. The URL must have a path, no port, credentials or fragment, and be a public host name. The document must contain `client_id` (identical to the URL), `client_name` and `redirect_uris` (1 to 5 exact HTTPS callbacks, or loopback `http://127.0.0.1`, `http://[::1]` or `http://localhost` callbacks whose port may vary), and may list `grant_types` (`authorization_code`, `refresh_token`, `urn:ietf:params:oauth:grant-type:device_code`). `token_endpoint_auth_method` must be `none`; secrets and keys are not accepted. Postedly fetches the document when it first sees the URL, does not follow redirects, accepts at most 16 KiB served as JSON within a few seconds, and caches it for the lifetime your `Cache-Control` header allows (5 minutes to 24 hours, 1 hour by default). The authorization server metadata advertises `client_id_metadata_document_supported`.
2. **Dynamic client registration (deprecated by the MCP specification, still supported).** `POST https://postedly.com/oauth/register` with `client_name` and 1 to 5 `redirect_uris` you control. HTTP 201 returns a `client_id`. Clients are public: no client secret is issued and `token_endpoint_auth_method` is `none`.
   Hosted agents must use an HTTPS callback controlled by their integration. Never substitute example.com or another unrelated website when a localhost callback fails: that exposes the authorization code. If your hosted agent has no callback at all, use the device flow below instead.
3. **Send the person to authorize** at `https://postedly.com/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope`, a fresh `state` and a PKCE `code_challenge` with `code_challenge_method=S256`. The person signs in by verifying their email, then approves the requested scopes. The page shows the application and the host it returns to; loopback-only clients get an extra warning. Do not call the internal consent API or ask for codes in chat. The authorization response carries `iss`; compare it with the issuer you recorded from the metadata (`https://postedly.com`) before sending the code anywhere.
4. **Exchange the code** within five minutes: `POST https://postedly.com/oauth/token` (form-encoded) with `grant_type=authorization_code`, `client_id`, `code`, the exact `redirect_uri` and the original `code_verifier`. The response contains `access_token` (one hour), `refresh_token` (30 days, rotated on each refresh) and `scope`.

### Device code sign-in (RFC 8628)

For a hosted agent that cannot receive a callback. Register with `POST /oauth/register` sending `grant_types` of `["urn:ietf:params:oauth:grant-type:device_code","refresh_token"]` and no `redirect_uris` (or use a metadata document whose `grant_types` lists the device grant), then:

1. `POST https://postedly.com/oauth/device_authorization` (form-encoded) with `client_id`, and optionally `scope` and `resource`. The response has `device_code`, `user_code` (eight letters, shown as `XXXX-XXXX`), `verification_uri` (`https://postedly.com/connect/device`), `verification_uri_complete`, `expires_in` (600 seconds) and `interval` (5 seconds).
2. Show the person the `user_code` and the verification URL. They open it in their own browser, enter the code, sign in by verifying their email and approve exactly the scopes you asked for. Never ask for their email code.
3. Poll `POST https://postedly.com/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `device_code` and `client_id`, no faster than `interval`. Errors: `authorization_pending` (keep waiting), `slow_down` (add 5 seconds to your interval), `access_denied` (the person refused; stop), `expired_token` (start again). A code works once. Success returns the same token response as above.

Device-flow credentials receive the narrower correspondence profile and carry the same scopes and limits as any other credential. A device code never approves or pays for an order. Code entry is rate limited, and device authorizations are logged.

Optional `resource` parameter: `https://postedly.com/mcp/send`, the only resource this authorization server issues tokens for. The token works for the MCP endpoint and the HTTP API.

## Scopes

| Scope | Allows |
| --- | --- |
| `orders:read` | Read the connected person's orders |
| `quotes:write` | Upload/preview documents and prepare handoffs and quotes |
| `checkout:write` | Create a private review link; request permitted cancellation |
| `contacts:read`, `contacts:write` | Read or change saved contacts, when the person asks |
| `drafts:read`, `drafts:write` | Read or change saved drafts, when the person asks |

## Use credentials

- Send `Authorization: Bearer <access_token>` on `https://postedly.com/mcp/send` and on protected HTTP API requests (paths under `/api/`, described in `https://postedly.com/openapi.json`). Never put tokens in URLs, chat, logs or source control.
- Refresh with `grant_type=refresh_token`. Serialize refreshes: reusing a retired refresh token revokes the whole grant, and the person must reconnect.
- Revoke with `POST https://postedly.com/oauth/revoke` (`client_id`, `token`).
- A `401` response carries `WWW-Authenticate: Bearer resource_metadata="..."` pointing at the protected resource metadata.

## What a credential cannot do

A token cannot pay. Physical mail and faxes are paid services, and every order is paid by the person through hosted Stripe Checkout in their own browser. For document/card orders, agents should use `postedly_checkout` (or the review link it returns): the person reviews the exact proof, recipient and total on a private Postedly page and approves there. The HTTP `POST /api/checkout` endpoint records approval only on the person's explicit instruction for that exact quote and returns a checkout URL for them to pay; never call it to approve on your own. Connecting an agent is not approval of any order.


More detail: `https://postedly.com/agent-guide.md`. Support: `https://postedly.com/support`.
