API keys

Every request sends an API key in its Authorization header, as Bearer and the key. Anyone in an account can create, rotate, and revoke its keys, on the API keys page of the dashboard. A key is shown once, when it's made, so copy it then. Getting started walks through making your first one.

Server keys

A server key starts with mapricot_sk_ and works from anywhere, so keep it secret. Use one for code on your servers, scripts on your own computer, and mobile apps. Never put it in a web page, and keep it out of your code and git: read it from an environment variable.

export MAPRICOT_KEY="mapricot_sk_…"

A mobile app sends no origin, so a browser key doesn't work there. Anyone who unpacks the app can read its key, though, so give an app's server key only the products it needs and caps, or send its requests through your own server.

Browser keys

A browser key starts with mapricot_pk_, for code in a web page. Anyone who opens the page can read it, so it works only from the sites listed under Allowed origins, one per line. An origin is a scheme, a host, and an optional port, with no path, such as https://example.com.

• *. matches any subdomain: https://*.example.com matches https://shop.example.com, but not https://example.com, so list that too if you need it.
• :* matches any port. Add http://localhost:* while you build, so the key works from pages served on your own computer.

A request from any other origin, or with no origin, gets 403 and "Key is not allowed from this origin," and isn't billed. A page opened straight from a file, with a file:// address, has no origin, so serve it with a local web server instead, such as npx serve or python3 -m http.server in its folder.

Outside a browser, anyone can send a request that claims to come from your site, so allowed origins don't stop a copied key on their own. Give a browser key only the products the page needs, and caps. JavaScript in the browser shows a browser key in use.

Products

Each key can use only the products picked for it, which the API calls scopes:

• Places (places) for geocoding and place search
• Routing (routing) for routes
• IP geolocation (ip-geolocation) for IP lookups

A request to a product the key doesn't have gets 403 product_disabled. Map tiles need no key.

Caps and expiry

Any key can have caps, so a copied key can't use up your free requests or credit:

• Requests per minute, counted in each clock minute.
• Requests per 30 days, counted over your account's billing period. A cap below 250,000 keeps the key inside the free allowance.

A request over a cap gets 429 and isn't billed. Requests already in progress when a cap is reached still finish, and are billed.

A key can also have an expiry date, after which it gets 401 like a revoked key. A key's products, origins, caps, and expiry can't be changed once it's made. To change them, create a new key with the settings you want, switch to it, and revoke the old one.

Rotate a key

Rotating a key replaces it without downtime. In the key's menu, choose Rotate, and choose when the old key stops working: now, in an hour, in a day, or in a week. The new key has the same name, products, origins, and caps, and is shown once. Put it in your environment variables or page, deploy, and the old key stops on its own at the time you chose. Rotating doesn't move a key's expiry date.

Rotate a server key when someone who knew it leaves, or on a schedule, and a browser key when someone else is using it.

Revoke a key

Revoke in the key's menu stops a key now, and anything still using it gets 401. It can't be undone. If a server key leaks, rotate it with the old key stopping now, or revoke it, and look up its requests by request ID in your usage export. Security explains how keys are stored.

Errors

Key errors aren't billed. They use the same shape as every other error:

• 401 unauthorized: the key is missing, mistyped, revoked, or expired, or its account is disabled or deleted.
• 403 product_disabled: the key doesn't have the endpoint's product.
• 403 origin_not_allowed: a browser key was used from an origin it doesn't allow, or with none.
• 429 rate_limited: the key's requests per minute are used.
• 429 period_cap_reached: the key's requests per 30 days are used.