Authentication

API keys#

A default key is created when you subscribe to an API. You can create more keys, for example one per application or environment, in the API Keys section of the Enterprise dashboard.

• A key belongs to one subscription and only works with that subscription's API. Calling another API with it is rejected with API key is not valid for this product.
• A key stops working while its subscription is inactive, for example after a trial ends, and requests are rejected with Subscription is not active.
• Deleting a key revokes it, and requests that use it are rejected from then on.

Authorization header#

Send the key as a Bearer token in the Authorization header. This is the recommended way to authenticate:

Authorization: Bearer YOUR_API_KEY

Query parameter#

Where you cannot set headers, for example in a URL handed to a map library, pass the key in the apiKey query parameter instead:

https://enterprise.coveragemap.com/api/v1/status?apiKey=YOUR_API_KEY

When a request has both, the query parameter is used. URLs are often written to logs and browser history, so prefer the header whenever you can.

Associated domains#

You can restrict a key to your own websites by setting its Associated Domains in the dashboard. A restricted key only works for requests whose Referer header comes from one of those domains, which stops anyone who copies the key from your front end using it elsewhere.

• Enter each domain as a host name, such as app.example.com. The host of the full Referer URL is compared, so https://app.example.com/pricing matches.
• Subdomains are separate host names and must each be listed.
• Browsers send the Referer header for you.
• Requests from your own servers with a restricted key must send a matching Referer header themselves.
• A key with no associated domains can be used from anywhere.

Keeping keys secure#

• Keep unrestricted keys on your servers, in environment variables or a secrets manager.
• Never commit keys to source control.
• Use separate keys for development and production so you can revoke one without the other.
• To rotate a key, create a new one, deploy it, then delete the old key once nothing uses it.

Authentication errors#

Authentication problems are returned like any other rejected request: HTTP 400 with the reason in messages.errors. They are never billed. See Errors for the full list.