Guides

API keys

Generate, store, use, rotate, and revoke secret keys for trusted backend integrations.

When to use

Use API keys from servers, workers, CI, and automation.

Do not expose secret API keys in browser code or mobile apps. If a frontend needs SUMR data, route the request through your backend.

Format

Test and live keys are clearly prefixed.

Use test keys for non-production environments and live keys only for production systems.

terminal

$sumr_sk_test_<keyId>_<secret># test key$sumr_sk_live_<keyId>_<secret># live key

Generate

Create a scoped key for one account.

The generated secret is shown once. Copy it immediately and store it in your secrets manager.

terminal

$curl https://api.sumr.co/v3/identity/api-keys -H "Authorization: Bearer <user-access-token>" -H "Content-Type: application/json" -d '{"name":"Production backend","accountId":"<account-id>","scopes":["playbook:read","playbook:write"]}'# create key

Store safely

Treat secret keys like passwords.

✓

Use a production secrets manager, such as AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.

✓

Use encrypted CI/CD secrets for automation.

✓

Use local .env files only when they are excluded from git.

✓

Do not log request headers or paste live keys into support tickets.

Call the API

Send the key in x-api-key.

Each key belongs to one SUMR account. Grant only the scopes your integration needs.

terminal

$curl https://api.sumr.co/v3/playbook/catalogs -H "x-api-key: sumr_sk_live_<keyId>_<secret>"# list catalogs

Backend examples

Load keys from environment variables.

terminal

$const response = await fetch("https://api.sumr.co/v3/playbook/catalogs", { headers: { "x-api-key": process.env.SUMR_API_KEY!, accept: "application/json" } });# Node.js$requests.get("https://api.sumr.co/v3/playbook/catalogs", headers={"x-api-key": os.environ["SUMR_API_KEY"]}, timeout=30)# Python

Rotate and revoke

Replace exposed or unused keys quickly.

Create a new key with the same scopes.
Deploy the new key to your secrets manager.
Restart or redeploy the integration.
Confirm requests succeed with the new key.
Revoke the old key.

Errors

Fix auth errors before retrying.

401

Missing key, malformed key, revoked key, expired key, or wrong environment.

403

Key is valid but lacks the required scope or account access.

404

Resource does not exist or is not visible to this key.

429

Too many requests. Retry with exponential backoff.

5xx

SUMR could not complete the request. Retry idempotent operations with backoff.