Documentation menu
Keys and account
POST/v1/keys
Access and price
| Auth | No key. Not metered. |
|---|---|
| Price | Not metered: no quota, no credit. |
What it does
One-call signup: issues a provisional key and emails a magic verification link.
No key. Not metered.
Call it
bash
curl -fsS -X POST "https://api.mapmap.ai/v1/keys" \
-H "Content-Type: application/json" \
-d '{"allowed_origins":["string"],"device_id":"string","email":"string","label":"string","scope":"string","source":"string"}'Request body
application/json · IssueKeyRequest
| Field | Type | Required | Description |
|---|---|---|---|
| accept_tos | not stated | no | Must be literally true, anything else is a 400 echoing the
terms-of-service URL. |
| allowed_origins | string[] | no | Origins this key may be called from, e.g.
["https://app.example.com", "https://*.staging.example.com"].
At most 20; each is scheme://host[:port] with no path, and a
wildcard may only stand for a single subdomain label. Omit for an
unrestricted key, the default, and what a server-to-server
integration wants. |
| device_id | string | no | Email-less issuance only: an opaque, stable id for the app install (the apps' install id). Never stored as sent; only its hash is used, as a per-install daily issuance budget beside the per-IP one. At most 128 characters. Optional, and ignored when an email is given. |
| string | no | Email address; becomes the (lowercased) identity of the key.
Optional ONLY for the MapMap apps' own labels
([identity::EMAIL_OPTIONAL_LABELS]), which then get an email-less
anonymous key; every other caller must send one. | |
| label | string | no | Optional human-readable label for this key (shown on the account
page, e.g. "nightly-dispatch-agent"). Defaults to the email. |
| scope | string | no | "full" (the default) or "maps". A maps key may draw tiles,
read styles/fonts/sprites, geocode and read its own status, and
nothing else. |
| source | string | no | Optional channel tag naming where this signup came from
("chatgpt", "agent-recipe", "cursor" …). Lowercased and
restricted to [a-z0-9._-], at most 40 characters; anything else
is dropped, never rejected, attribution must not break signups. |
Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call
json
{
"allowed_origins": [
"string"
],
"device_id": "string",
"email": "string",
"label": "string",
"scope": "string",
"source": "string"
}Responses
201Provisional key issued; the
key field is shown once only| Field | Type | Required | Description |
|---|---|---|---|
| allowed_origins | string[] | no | The canonical origin allow-list stored for this key, echoed back so the caller can see exactly what was accepted (ports and case are normalised, duplicates dropped). Absent on unrestricted keys. |
| calls | integer | yes | Call allowance: in total until verified for a provisional key, per
calendar month for anonymous and verified keys. |
| claim_url | string | no | Zero-authority claim pointer for the HUMAN behind this agent: the
page shows a masked email and offers to send a sign-in link. Safe
to print in chat or logs; it grants nothing by itself. Present only
when the deployment has a console (SN_CONSOLE_URL). |
| code_expires_in_min | integer | no | Provisional keys only: minutes the emailed 6-digit code stays valid
([identity::KEY_CODE_TTL_MIN]). The link beside it lasts
[identity::VERIFY_TOKEN_TTL_HOURS] hours. |
| display_to_user | string | no | Sentence for the agent to show its human verbatim (contains the
claim URL, never the key). Present only alongside claim_url. |
| expires_in_h | integer | yes | Hours until the provisional key expires unverified; 0 for keys that do not expire. |
| key | string | yes | The full API key (snk_…). Shown once, never again. |
| key_id | string | yes | Key id (UUID), for /v1/keys/self correlation and admin ops. |
| resend_after | string | no | Provisional keys only: the RFC 3339 moment a new verification code
may be asked for (POST /v1/keys/self/verify/resend), so a page can
count down its Resend button. Present whether or not a mail went out
(the answer is the same for every address). |
| scope | string | no | "maps" when the key was minted map-scoped; absent for the full
surface. |
| state | string | yes | provisional at an ordinary issuance; anonymous for an email-less
app key; verified for the store-review identity. |
| tos | string | yes | Terms-of-service URL that was accepted. |
| verify | string | yes | What happens next. |
Example: A response assembled from this schema's own field examples, enums, defaults and types; not a recorded call
json
{
"calls": 0,
"expires_in_h": 0,
"key": "string",
"key_id": "string",
"state": "string",
"tos": "string",
"verify": "string"
}400ToS not accepted (body echoes the
tos URL), invalid/disposable email, or rejected allowed_origins/scope (body carries problems[])application/problem+json · Problem
413The request declares a body larger than 1048576 bytes (plain text, not problem+json)
text/plain
429Issuance velocity exceeded: per IP or per install (
limit_per_day), per address per hour for a key without an email (limit_per_hour), or the global hourly ceilingapplication/problem+json · Problem
504The request did not finish within the gateway's request deadline (
request-timeout)application/problem+json · Problem
Error bodies follow the shared problem model documented on API conventions.
Also under Keys and account
GET /.well-known/oauth-authorization-serverPOST /oauth/registerPOST /oauth/tokenDELETE /v1/keys/selfGET /v1/keys/selfPOST /v1/keys/self/emailPOST /v1/keys/self/email/verifyPOST /v1/keys/self/verifyPOST /v1/keys/self/verify/resendGET /v1/keys/verifyPOST /v1/keys/verifyPOST /v1/keys/verify/denyPOST /v1/keys/verify/detailsGET /v1/usage
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId issue_key