Authentication

Every request, except Check the API, carries one of your API keys in the Authorization header, as it is:

GET /api/v1/products HTTP/1.1
Host: api.measuremaponline.com
Authorization: YOUR_API_KEY

There is no Bearer in front of it and no other header to send. A request without a key, or with an unknown, revoked or expired one, is refused with 403 invalid_api_key.

Plans#

Keys work while your account is on a plan with API access and the subscription is active:

When a subscription lapses, requests answer 403 subscription_expired until it is active again; the keys themselves are kept.

Create a key#

Keys are made on the Developer page↗ of the app, under API keys:

1. Choose Live or Sandbox (see Live and sandbox).
2. Under Access for the new key, choose what the key may do.
3. Optionally give it a name, to tell your keys apart.
4. Press Generate new key. Copy it with the copy button.

You get an email whenever a key is created or revoked on your account. A new key can be made about once a minute.

Key access#

What a key may do is fixed when you create it. Each endpoint in the reference shows the access it needs.

• An endpoint the key has no access for answers 403 insufficient_scope; one your plan does not include answers 403 scope_not_in_plan.
• Products access is never given by default. Choose it when you create the key: a catalogue holds your prices, and a key in a web page should not be able to change them.
• Signing in as a member needs Members: write chosen explicitly on the key (see Sign in as a member).
• A key made before access areas existed can do everything except products and signing in as a member. Replace it with a narrower one when you can.

Replace a key#

Press Generate new key again. The new key starts working at once and the old one keeps working for 24 hours, so you can update your servers and pages without an outage. The old key is listed under Previous keys with the time it has left. To stop it at once, for example because it leaked, press Revoke.

Replacing a live key never affects your sandbox key, and the other way round. The new key keeps the old key's website restrictions.

Website restrictions#

A key can be limited to your own websites, under Website restrictions on the Developer page. A domain also covers its subdomains: example.com allows shop.example.com.

• Requests from a web page must come from a listed site. Browsers say where a request comes from (Origin, Referer), and the API checks it.
• Requests from a server carry neither header and are not checked.
• Embeds are checked strictly: the page showing the map must be on a listed site, and an embed that does not say where it is shown is refused.

A refused request answers 401 unauthorized_action.

Keep your keys safe#

• Give each key only the access it needs. A key in a web page, such as in an embed's address, should have Embed access only.
• Keep keys that read or change data on your server, in an environment variable or a secret store. Never put them in a mobile app, a public repository or front-end code.
• Use tokens in pages. Your server can exchange the key for a short-lived token and put that in the page instead.
• Restrict keys used in web pages to your own websites.
• Build with a sandbox key, so experiments never reach your real projects.
• If a key may have leaked, generate a new one and revoke the old one under Previous keys straight away.

Suspended access#

If API access on your account is suspended by our support team, every key answers 403 api_key_suspended and no new key can be made until it is lifted. Contact support.