Authentication

Authenticate every API request with your API key.

Overview

Every request to the API must include your API key. Send it in this header: X-API-Key

Keep your API key secret

Never expose your API key in client-side code or public repositories, and never share it. If it leaks, delete it from your dashboard and create a new one.

Getting Your API Key

Follow these steps to obtain your API key:

1

Create an account or sign in

Sign up for a new account or sign in to your existing one: Sign Up · Sign In

2

Open the API Keys page

Dashboard > API Keys

3

Create a new API key

Click "Create Key", give it a name and copy the generated key. Store it somewhere safe, such as an environment variable.

API Key Format

API keys are long random strings that start with key_

key_a1b2c3d4e5f60718293a4b5c6d7e8f901a2b3c4d5e6f7081

Making Authenticated Requests

Add the key to the headers of each request:

Two ways of sending the key are accepted:

  • X-API-Key: key_your_api_key recommended header
  • Authorization: Bearer key_your_api_key Bearer token, for clients that only support this scheme
curl "https://api.scrapemapsapi.com/v1/places/ChIJ8cLgoQNUKhMReGlaTjwrH40" \
  -H "X-API-Key: key_your_api_key"

Authentication Errors

If authentication fails, you receive one of the following errors. They are never billed.

Status CodeErrorDescription
401missing_api_keyNo API key in the request
401invalid_api_keyThe API key does not exist or has been disabled
402insufficient_creditsNot enough credits left for this call

Keys and credits

All the keys of an account share one credit balance: the free monthly calls are spent first, then the credits you bought, which are valid for 12 months from purchase (the ones that expire first are used first). A call is billed only when it answers HTTP 200, so a request refused for a missing or wrong key costs nothing.

Every successful response says what it cost in the X-Credits-Used header and what is left in X-Credits-Remaining, so a script can stop before the balance runs out. When it does, the API answers 402 insufficient_credits until you top up.

Best Practices

Use environment variables

Store your API key in environment variables, not in your code.

Use different keys for different environments

Create separate API keys for development, staging and production.

Rotate keys periodically

Replace your API keys from time to time to limit the impact of a leak.

Never expose keys client-side

Call the API from your server, not from browser JavaScript.

Next Steps