API keys

An API key lets your own website or software work with your Measure Map Online account: show a project's map on your site, start projects for your visitors, or read and change projects through the REST API. You create and manage keys on the codeDeveloper page.

Open the Developer page#

In the dashboard menu, under Advanced, press codeDeveloper. It opens on vpn_keyAPI keys, and its other sections are listed under it in the menu (on a phone, as tabs at the top of the page):

• person_pin_circleGuest link (Open Guest): the no-code link for your website. See Open Guest.
• terminalTry the API, webhookWebhooks and apiREST API: see the API reference.
• web_assetEmbed a map (Enterprise): see the iFrame API.

The badge at the top of the key card says whether your key is Active, Not activated (no key yet), Disabled (API access suspended: no key works and no new one can be made until support lifts it) or Expired (the subscription is not active).

Live and Sandbox#

At the top of the key card, switch between public Live and science Sandbox. Each has its own key, and the page shows the one you pick. The choice also applies in terminalTry the API, and it stays while you move between sections. web_assetEmbed a map and person_pin_circleGuest link always use your live key, because visitors to your website can only open live projects: opening either one switches the page back to Live.

• Live is your real account, and the page opens on it. Use a live key on your website.
• Sandbox is for building and testing an integration. Projects, folders and products made with a sandbox key are kept apart from your real ones: a live key cannot see them, and a sandbox key cannot see your live ones. Requests made with a sandbox key are not counted in your usage figures, and guest projects made with one are never billed.

Making a new sandbox key never affects your live key, and the other way round.

Choose what the key can do#

Under Access for the new key, each row is one area of the API. Choose how far the next key you create reaches into it:

Hold the pointer over a choice to see exactly what it grants. Your first key starts with Embedded maps only, which is all an embedded map needs; a key that replaces another starts with that key's access. Choose at least one area. Signing in as one of your organisation's members through the API needs Users: Read & change, not Embedded maps.

What a key may do is fixed when you create it. To give a key more or less access, create a new one.

Create a key#

1. Choose Live or Sandbox.
2. Set the access under Access for the new key.
3. If you like, type a name in Name for the new key (optional), to tell your keys apart.
4. Press refreshGenerate new key.

The key appears under Your API key, hidden except for its first and last characters, with a line saying what it Can do. Press visibility to show it in full, or content_copy to copy the whole key. You get an email each time a key is created on your account.

A key made before access areas existed can do everything except work with products and sign in as a member; the card warns you about it. Replace it with a narrower one if you only use it for embeds.

Replace a key#

Press refreshGenerate new key again when you have a key. The app warns you first: A new key will be created and your current key will keep working for 24 hours, so you can update the sites that use it. You can revoke it sooner once you are done.

The old key moves to Previous keys, with the time it has left and when it was last used. Still accepted while you roll the new key out. Revoke one as soon as nothing is using it. To stop it at once, press blockRevoke and confirm; any site still using it stops working immediately. You get an email when a key is revoked.

Your website restrictions are copied to the new key. You can create a new key about once a minute.

Restrict the key to your websites#

Only the websites on this list can use your key in a browser: embedded maps and requests from pages on any other site are refused. Calls from a server are not affected.

1. Under Website restrictions, type your site in Enter a website or domain: a domain such as example.com, an IP address or localhost. You can paste a full address: only the site's name is kept, without https://, the path or the port.
2. Press addAdd.

A domain also covers its subdomains: example.com allows shop.example.com. Press delete_outline to remove a site, and confirm; after the last one, the key works from any website. You get an email whenever a website is removed from a key.

The list applies to browsers. An embedded map opens only on a page of a listed website; when the browser does not say which page it is on, it is refused. A REST API request sent from a web page must come from a listed website. A request from your own server names no website and is not checked. Measure Map Online itself is always allowed, so the previews on this page keep working.

See how the key is used#

Usage adds up all your live keys, so the figures carry on when you replace a key. It shows the requests of the last 30 days, from embedded maps and the REST API alike, with a bar for each day; the total All time; the Last access; when the current key was created (Key created); and the Top domains: the websites that use your keys most. A website you do not recognise there is a reason to restrict or replace the key.

Sandbox requests are not counted, so the figures show on Live only. Nor are the requests this page makes itself, in terminalTry the API and the previews.

Keep your key safe#

• Give each key only the access it needs. A key in a web page (for example in an embed's address) should have Embedded maps only.
• This key can change your data. Keep it on your server, never in a web page or an app.
• Restrict a key used in web pages to your own websites.
• Leave the key hidden on the page when you share your screen; copying it never needs it shown.
• If a key may have leaked, create a new one and revoke the old one under Previous keys straight away.
• Build and test with a Sandbox key, so experiments never land among your real projects.