API key security

The SOPCompass REST API is available on the Business plan. For how to create and use keys, see Authentication and API keys. This page covers how keys are protected.

How keys are made and stored

• A key is sc_live_ followed by 64 hexadecimal characters: 32 bytes from a cryptographic random generator, created inside the database.
• It is returned once, when it is created. SOPCompass stores only its SHA-256 hash and a display hint.
• The table that holds key hashes has row-level security on, no policies and no grants, so it can’t be read through the app or the API at all. Keys are created, listed and revoked only through database functions that check your role.

Who can manage keys

• Only owners and admins can create, list and revoke keys.
• A workspace can have up to 25 active keys.
• Creating a key requires the Business plan and an active subscription. An owner or admin of a lapsed workspace can still list and revoke keys.

What a key can reach

• One workspace, the one it was created in, plus libraries shared into that workspace, read only.
• Read only keys can call GET endpoints. Read and write keys can also create SOPs (always as unpublished drafts) and assignments.
• A key sees what a member of its workspace would see. It can’t reach any other workspace.
• Writes from a lapsed workspace are refused, the same as in the app.

Checks on every request

Every call goes through one database gate that, in order, checks the key’s format, looks up its hash, refuses revoked keys, refuses keys whose creator is no longer an owner or admin of the workspace (401 creator_not_admin), applies the rate limit, checks the plan, and for writes checks the key’s scope and the workspace’s billing.

• Rate limit: 60 requests per key per calendar minute. Over the limit you get 429 rate_limited with a Retry-After header.
• Keys in URLs are refused. A key sent in the query string is rejected with 401 key_in_url, even if a header is also sent, so keys don’t end up in logs and browser history.
• Last used is recorded (at most once a minute), so you can spot keys that are unused or used unexpectedly.

Keeping keys safe

1. Give each integration its own key, named after it.
2. Use a read only key unless the integration must write.
3. Keep keys in a secret manager, never in code, spreadsheets or client side JavaScript.
4. Revoke a key as soon as it is no longer needed, or if you think it leaked. Revoking takes effect on the next request.