Authentication

Authenticate every request with an API key.

Create a key

Go to API keys in the console and create one. It’s shown once, so copy it then. Keys belong to your organization, so they keep working when the person who created them leaves.

Send the key

Send the key as a bearer token in the Authorization header:

Terminal

curl 'https://api.placestack.com/v1/jurisdiction?q=hartland&state=MI' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY"

Don’t put the key in a URL.

Managing keys

Create a separate key for each app or environment, so you can revoke one without stopping the others. Revoke a key on the API keys page.

Errors

A request without a usable key gets a 401. Branch on the code:

JSON

{
  "type": "https://placestack.com/docs/api/error#credential_missing",
  "title": "API key missing",
  "status": 401,
  "detail": "Send your API key as Authorization: Bearer <key>.",
  "code": "credential_missing"
}

CodeDescription

credential_missingThe request had no API key. Check that the Authorization header is set and the key variable isn't empty.

credential_invalidThe key is not valid. Check it was copied in full and hasn't been revoked on the API keys page.

credential_expiredCreate a new key and replace the old one.

Next steps

Errors

What each status and error code means, and what to do.

Continue