API keys
Create and manage keys to use Cipher from your own applications.
API keys authenticate requests to the Cipher API. You create and manage them in Settings, then Connectors (or in the developer console).
Key types
Cipher keys come in two forms:
- Secret keys start with
cipher_sk_. Use them only on a server. They can run every level your plan allows and should never be exposed in client side code. - Publishable keys start with
cipher_pk_. Safe to use in the browser for lighter, client side validation.
A key looks like this:
cipher_sk_aB3dEf... (49 characters after the prefix)Treat secret keys like passwords
A secret key is shown in full only once, when you create it. Store it somewhere safe. If a key leaks, disable it and create a new one.
Creating a key
- Open Settings, then Connectors.
- Under API keys, give the key a name (for example, Production or Staging).
- Click Create key and copy the value.
You can create multiple keys, name each one, disable a key temporarily, or revoke it permanently. Naming keys per environment or per service makes it easy to rotate or revoke one without affecting the others.
What a key controls
Each key carries:
- Level limit. The highest Cipher level the key may request: Basic, Pro or
Max. Asking for a higher level returns a
TIER_NOT_AVAILABLEerror. - Credits. Each validation spends one credit. When a key runs out you get an
INSUFFICIENT_CREDITSerror until it is topped up. - Rate limit. The maximum requests per window for that key.
Authenticating
Send the key as a bearer token on every request:
curl https://surbee.dev/v1/cipher/validate \
-H "Authorization: Bearer cipher_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "level": 2, "thresholds": { "fail": 0.5, "review": 0.75 }, "input": { } }'Responses include two helpful headers:
X-Cipher-Request-Idfor support and debugging.X-Cipher-Credits-Remainingso you can track usage.
Next: Cipher SDK and API.