API Keys & Access

Overview

API keys are the main way to authenticate requests to Mappinest APIs and control access to your data. You can find them in the console under Access → API Keys. When you are logged in, the default API key is automatically embedded in docs examples and studio previews.

API keys are passed through the ?key=<key> query parameter on request URLs. You can create additional keys when you need separate scopes, domain rules, or environments.

What you can do in this section

• Create and rotate API keys from one console view.
• Control scopes and key type (web, desktop, or server).
• Restrict browser access with domain allowlists and CORS checks.
• Restrict access to specific tilesets using username.tileset IDs.

Create and manage API keys

Use the API Keys page in the console to create keys, rotate the default key, and edit key policies for production use.

Create key form

Use this button to create API key dialog with key type, scopes, and domain restriction fields.

Edit key policy form

Edit form for an existing key with updated scopes, domains, and tileset restrictions.

Key types

Key type defines where a key can be used by default. Start with Any (unrestricted) during setup, then move to web, desktop, or server when you want tighter production rules.

Scopes

Scopes are optional. If you set any scopes, tiles access requires tiles:read. If scopes are empty, requests are not blocked by scopes.

• tiles:read
• styles:read
• static:read
• export:read

URL restrictions

Add domains to restrict browser access. When the list is non-empty, the request must include an Origin header and the host must match the allowlist. Domain restrictions rely on this browser Origin header and enforce the allowlist at request time.

• Browser sends Origin with the request.
• Mappinest compares Origin against allowed_domains on the API key.
• If it matches, the request is allowed and CORS response headers are returned.
• If it does not match, the request is rejected before tile data is returned.

• Production web app

  https://www.mappinest.com

• Staging app

  https://app.example.com

• Local development

  http://localhost:3000

Limits

Rules at a glance

• No restrictions (no domains, no tilesets, no scopes, key type unset) means the key works in browser and non-browser clients.
• If allowed_domains is set, Origin is required and must match. Non-browser requests are blocked.
• If key type is web and no domains are set, Origin is still required and any host is allowed.
• If key type is desktop or server and no domains are set, Origin is optional.
• If allowed_tilesets is set, only those tilesets are allowed.
• If scopes is set, tiles:read must be present for tile access.

Desktop GIS

Use a desktop or server key (or an unrestricted key). If allowed_domains is set, desktop clients will be rejected because they do not send Origin.