Authenticate API requests

Secret and publishable keys

Both kinds are created under Settings → Developers. Create and manage API keys shows how. A key belongs to your workspace, not to the person who created it, so it keeps working when people join or leave your team.

What keys look like

The rest of a key is random and says nothing about your workspace. The prefix lets you, and tools that scan code for leaked secrets, tell the kinds apart. Settings shows the first few characters of each key, so you can tell your keys apart after the key itself is gone from view.

Send the key as a bearer token

Send your secret key in the Authorization header of every request:

Authorization: Bearer sk_live_…

The samples in these docs read the key from an environment variable called SKIPSHOOT_SECRET_KEY, so it never sits in your code:

curl https://www.skipshoot.com/api/v1/me \
  -H "Authorization: Bearer $SKIPSHOOT_SECRET_KEY"

A working key answers with its workspace’s name and credits. See Retrieve your account.

Keep secret keys safe

• Keep secret keys in an environment variable or your platform’s secret manager. Never commit one to a repository, even a private one.
• Call the API only from your servers. A secret key in a web page or a mobile app can be read by anyone who has it.
• Create one key for each system that calls the API, named for it, such as “PIM sync”, so you can revoke one without stopping the others.
• Rotate keys on a schedule, and whenever someone who had access leaves. See Rotate a key.
• Turn on secret scanning for your repositories, so a key committed by mistake is caught. See Catch leaked keys.

Authentication errors

A 401 response also carries the header WWW-Authenticate: Bearer.

{
  "error": {
    "type": "authentication_required",
    "message": "Send your API key as Authorization: Bearer <key>."
  }
}