Skip to main content

Authentication

Rendering needs no API key. Both endpoints are open: build a URL, request it, get a map. You don't need an account.

API keys exist for one purpose, described below.

What a key does​

A key decides whether the maproll wordmark can be turned off for renders tagged as coming from the maproll MCP server (src=mcp). Those renders carry the wordmark unless the request presents a valid key.

A key does not raise a limit, enable a parameter, change the image, or grant access to anything that is otherwise refused. For every other caller — a plain <img> embed, a curl, the editor — logo=false already works without a key. See Attribution & logo.

Where to pass a key​

Either header works:

Authorization: Bearer mr_live_…
X-Api-Key: mr_live_…

A key is never read from the query string, because a key in a URL ends up baked into whatever embed someone shares.

Keys are minted from the API keys panel in the maproll editor. They are prefixed mr_live_. The full key is shown once, at creation, and cannot be recovered afterwards. Each key expires 90 days after it is minted.

For the MCP server, the key goes in the environment as MAPROLL_API_KEY rather than in a header — the server signs the URLs it returns so that an <img> embed can be keyed without carrying the key. See Install.

Revoking and expiry​

Revoking is not immediate. Deleting a key in the editor removes it from the panel and stops it signing anything new, but requests already signed with it keep verifying until the key's 90 days are up.

The same applies to expiry in the other direction. When a key expires, an MCP-made embed URL you published months ago starts carrying the wordmark again. Rotate before the 90 days are out, and re-render anything keyed that is already published.

What a key changes about caching​

Where the key travels decides this:

RequestCache-Control
Anonymouspublic, max-age=31536000, immutable
Key in a headerprivate, no-store
MCP-signed URL (k and t)public, max-age=31536000, immutable

A header-keyed response is never stored by a shared cache.

A signed URL stays immutably cacheable, which makes a keyed map safe to embed at scale. Calling the render API directly with a header key gives up caching.

Rate limits​

There are no rate limits during the preview. This may change, so don't depend on unlimited throughput.

Fair use today​

While the service is open:

  • Renders are aggressively cached. Re-using the same URL is free — please do.
  • Avoid generating thousands of unique URLs in a loop. Each distinct URL is a fresh render.
  • PNG output costs meaningfully more CPU than SVG, because the SVG is rasterized server-side. Prefer .svg where the embedding context supports it.