Authentication and API keys

Every request is authenticated with an API key. A key belongs to exactly one workspace, the one it was created in, and every request made with it is scoped to that workspace.

Who can create keys

• The workspace is on the Business plan.
• You are an owner or admin of the workspace.
• The workspace’s subscription is active. Once a subscription has ended, new keys can’t be created: the app shows “This workspace’s subscription has ended, so new API keys can’t be created.” Existing keys can still be listed and revoked.
• The workspace has fewer than 25 active keys. Revoke one you no longer use to make room.

Create a key

1. Open People, then Settings & billing, and scroll to API keys.
2. Under New key name, name the key after what will use it, such as Zapier or HR sync. Names are up to 80 characters.
3. Under Access, pick a scope (see below).
4. Click Create key.
5. Click Copy and store the key in your secret manager or your integration’s credential store.
6. Click I’ve saved it.

Important: The key is shown once. SOPCompass stores only a SHA-256 hash of it, so a lost key can’t be recovered or shown again. If you lose it, revoke it and create another.

A key looks like sc_live_ followed by 64 lowercase hexadecimal characters. After creation, the key list shows only a hint such as sc_live_ab12...9f3c, plus who created the key, when, and when it was last used (updated at most once a minute).

Scopes

A read only key calling a POST endpoint gets 403 read_only_key. The scope can’t be changed after creation; create a new key instead.

Give each integration the smallest scope it needs. A sync job or a chatbot only reads, so give it a read only key.

Send the key

Send the key in the Authorization header, as a Bearer token, on every request:

curl https://app.sopcompass.com/api/v1/sops \
  -H "Authorization: Bearer $SOPCOMPASS_API_KEY"

const res = await fetch("https://app.sopcompass.com/api/v1/sops", {
  headers: { Authorization: `Bearer ${process.env.SOPCOMPASS_API_KEY}` },
});

import os
import requests

res = requests.get(
    "https://app.sopcompass.com/api/v1/sops",
    headers={"Authorization": f"Bearer {os.environ['SOPCOMPASS_API_KEY']}"},
    timeout=30,
)

The word Bearer is not case sensitive. Nothing else authenticates a request: there are no cookies, sessions or query-string keys.

Never put a key in a URL

A request whose query string contains a key is refused with 401 key_in_url, even if a valid Authorization header is also present. URLs are written to server logs, proxy logs and browser history, so treat any key that has appeared in a URL as leaked: revoke it and create a new one.

Keep keys off the client

Keys are server-side credentials. Don’t put them in a web page, a browser extension, a mobile app or a public repository: anyone who can read the page’s source can copy the key and act as your workspace. Call the API from your server, a serverless function or a no-code tool’s credential store. See Security best practices.

When a key stops working

Every 401 response except key_in_url also carries a WWW-Authenticate: Bearer header.

Keys follow their creator

A key acts with the authority of the owner or admin who created it. If that person is removed from the workspace or changed to editor or viewer, every key they created stops working with 401 creator_not_admin:

{
  "error": {
    "code": "creator_not_admin",
    "message": "The person who created this API key is no longer an admin of this workspace, so the key stopped working. An admin can create a new one."
  }
}

Promoting the person back to admin makes their keys work again. Otherwise an admin creates a replacement key and updates the integration.

Important: Create keys for long-running integrations from an admin account that will stay an admin, such as the workspace owner’s, so the integration doesn’t break when someone changes roles or leaves.

Assignments made through the API are also recorded as assigned by the key’s creator. See Assign an SOP.

Plan and billing changes

If the workspace moves off the Business plan, its keys are kept but every request answers 403 plan_required until it moves back. If the subscription ends, keys can still read but writes answer 403 workspace_read_only, the same read only state the app shows.

Revoke a key

1. Open People, then Settings & billing, then API keys.
2. Find the key and click Revoke, then Revoke now.

Revoking takes effect on the next request: it answers 401 revoked_key. Revoked keys stay in the list, marked with the date they were revoked, so you have a record. A revoked key can’t be restored.

Rotate a key

There is no rotate button; rotation is create, switch, revoke:

1. Create a new key with the same scope, named after the same integration (for example HR sync 2026-10).
2. Update the integration to use the new key and confirm it works. The new key’s last used time in the key list confirms traffic.
3. Revoke the old key. Its last used time should stop changing once nothing uses it.

Rotate on a schedule that suits you, immediately when someone who had access to a key leaves, and immediately if a key may have been exposed.