# MapPoster auth.md

This file tells AI agents how to get access to MapPoster (https://mapposter.xyz) for the person they work for. Most of MapPoster needs no account and no credentials.

- **MCP server** `https://mcp.mapposter.xyz/mcp`: no sign-in. Finds places, lists themes and designs posters.
- **Render API** `https://api.mapposter.xyz`: a Bearer API key from a paid plan. Renders poster files.
- **Editor** `https://mapposter.xyz`: no account. Downloads and print orders are paid for there by the person.

## Discover

MapPoster runs no OAuth or OpenID Connect server and publishes no OAuth metadata, so there is no agent registration endpoint. An agent cannot create an account or a key by itself: a key comes with a plan that a person buys.

Machine-readable descriptions: the API catalog at https://mapposter.xyz/.well-known/api-catalog, the Render API's OpenAPI at https://mapposter.xyz/openapi.json and the MCP Server Card at https://mapposter.xyz/.well-known/mcp/server-card.json.

## Pick a method

| You want to | You need |
|---|---|
| Find a place, list themes, design a poster and get a link that opens it in the editor | Nothing: use the MCP server |
| Let the person download the poster (free PNG up to 1080px with a small watermark, or the premium file) or order a print | Nothing: give them the editor link; they download, or pay, on mapposter.xyz |
| Render poster files yourself (SVG, PDF, PNG, JPEG, WebP), for example for print on demand | A Render API key (`mpk_live_…`) |

Never enter payment details for the person: every payment happens on a page they open themselves.

## Get a Render API key

Plans: Starter (100 renders a month), Pro (1,000), Business (5,000) and Single Render (one render). Prices and the commercial use licence are on https://mapposter.xyz/developers/.

The person can buy a plan on that page and give you the key. Or you start the checkout for them:

1. Ask which plan they want, then create the checkout:

   ```http
   POST https://api.mapposter.xyz/v1/checkout
   Content-Type: application/json

   {"plan": "starter", "email": "person@example.com"}
   ```

   The answer is `{"url": "https://checkout.stripe.com/…", "id": "cs_…"}`. `plan` is `starter`, `pro`, `business` or `single`; `email` is optional.

2. Give the person the `url`. They pay on Stripe's page.

3. Stripe then sends them to https://mapposter.xyz/developers/, which shows the new key once. Ask them for it.

   If they left before that page loaded, the key can be fetched once with the checkout's `id`:

   ```http
   GET https://api.mapposter.xyz/v1/key?session_id=cs_…
   ```

   - `202` `{"pending": true}`: the payment is still being confirmed; ask again in a few seconds.
   - `200` `{"key": "mpk_live_…", "key_prefix": "…", "plan": "starter"}`: the key. Store it safely and give it to the person; it is not shown again.
   - `410`: it was shown already. A lost key is replaced by rotating it (below).

## Use the key

- **Render API:** send `Authorization: Bearer mpk_live_…` with every `/v1/` request. `POST /v1/render` makes a poster file; `GET /v1/me` shows the plan, status and renders left this month.
- **MCP server:** the same key adds the `render_poster` and `get_render_usage` tools. Send it as `Authorization: Bearer mpk_live_…`, or, in clients that can't send headers, in the URL: `https://mcp.mapposter.xyz/mcp/mpk_live_…`. The MCP server passes it on to the Render API only.

Keep the key out of pages, logs and shared chats: anyone who has it can use up the plan's renders.

## Errors

| Status | Meaning | What to do |
|---|---|---|
| `401` | Missing or invalid key | Check the `Authorization` header; the key may have been rotated |
| `402` | No render credits left (Single Render) | Buy another, or subscribe |
| `403` | Key suspended (payment failed) or revoked (subscription ended) | The person renews the plan |
| `429` | This month's renders are used up | Wait for the 1st of the month (UTC), or upgrade |

## Revocation

- Rotate a key: `POST https://api.mapposter.xyz/v1/keys/rotate` with the key as Bearer token. The old key stops working at once; the new one is in the answer, once. The "Manage your key" form on https://mapposter.xyz/developers/ does the same.
- Ending the subscription revokes its key; a failed payment suspends it until the plan is paid again.

Questions: mapposterxyz@gmail.com