self-serve

One-call signup: issues a provisional key and emails a magic verification link.

post/v1/keys

Request

  • Base URL: https://api.mapmap.ai
  • URL: https://api.mapmap.ai/v1/keys
  • Auth: none declared

Request body

accept_tosunknown
allowed_originsstring[] nullable

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_idstring nullable

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.

emailstring nullable

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.

labelstring nullable

Optional human-readable label for this key (shown on the account page, e.g. "nightly-dispatch-agent"). Defaults to the email.

scopestring nullable

"full" (the default) or "maps". A maps key may draw tiles, read styles/fonts/sprites, geocode and read its own status, and nothing else.

sourcestring nullable

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.

Response

Provisional key issued; the key field is shown once only

allowed_originsstring[] nullable

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.

callsinteger required

Call allowance: in total until verified for a provisional key, per calendar month for anonymous and verified keys.

claim_urlstring nullable

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).

display_to_userstring nullable

Sentence for the agent to show its human verbatim (contains the claim URL, never the key). Present only alongside claim_url.

expires_in_hinteger required

Hours until the provisional key expires unverified; 0 for keys that do not expire.

keystring required

The full API key (snk_…). Shown once, never again.

key_idstring required

Key id (UUID), for /v1/keys/self correlation and admin ops.

scopestring nullable

"maps" when the key was minted map-scoped; absent for the full surface.

statestring required

provisional at an ordinary issuance; anonymous for an email-less app key; verified for the store-review identity.

tosstring required

Terms-of-service URL that was accepted.

verifystring required

What happens next.

Changes

No recorded changes to this operation across all 1 revision of this API.