Authenticate with API keys

Create scoped API keys, send them in the Authorization header and rotate them safely.

Updated 6 days ago 2 min read v2

On this page

Create an API key
Send the key
Test keys
Rotate a key

Every request to the Acme Cloud REST API must include an API key. Keys belong to a workspace and can be limited to specific projects and permissions.

Create an API key#

Go to Settings → API keys.
Click Create key, name it after where it will be used (for example “GitHub Actions”).
Choose scopes, such as deployments:write or projects:read.
Copy the key now — it is shown only once.

Send the key#

Pass the key as a bearer token:

GET /v2/projects

curl https://api.acme.example/v2/projects \
  -H "Authorization: Bearer $ACME_TOKEN"

const res = await fetch('https://api.acme.example/v2/projects', {
  headers: { Authorization: `Bearer ${process.env.ACME_TOKEN}` },
});
const { data } = await res.json(); // list of projects

import os, requests

res = requests.get(
    "https://api.acme.example/v2/projects",
    headers={"Authorization": f"Bearer {os.environ['ACME_TOKEN']}"},
)
print(res.json()["data"])  # list of projects

$ch = curl_init('https://api.acme.example/v2/projects');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . getenv('ACME_TOKEN')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$projects = json_decode(curl_exec($ch), true)['data'];

Test keys#

Keys that start with acme_test_ work against a sandbox and never touch production.

Rotate a key#

Create the new key first, update your secrets, then revoke the old key. Revoked keys stop working within a minute.

Keep keys secret

Never commit API keys to Git. If a key leaks, revoke it immediately — GitHub secret scanning will also notify us.

Was this article helpful?

81% found this helpful