How does authentication with your API key work?

You need an API key for every call over https. The key determines which account you are working on: there is no separate username and no token that expires.

Sending your key

Authentication uses basic auth. You enter your key as the username and leave the password blank. In curl, place a colon after the key, otherwise curl will still ask for a password.

To see how this works with the ‘Try it’ button in this documentation, read Trying out the API with Try it.

curl https://api.laposta.nl/v2/list \
  -u YOUR_API_KEY:

If you do not send a valid key, the API returns a 401 error message:

{
  "error": {
    "type": "invalid_request",
    "message": "No valid API-key provided"
  }
}

Creating a key

You can create keys in your account under ‘Connect’. To find out how to do this, what you can still see of a key afterwards and how many keys you can create, read Create an API key.

Keeping your key safe

A key grants access to all data in the account, so treat it like a password.

Instead, use an environment variable or the secrets storage of your hosting provider, and run the calls from your own server. If you want to test something, use a separate list in your own account. Make sure to do this for endpoints that create or delete data. Creating a separate free test account is usually not possible: see One free account per organisation.

Related articles