Skip to main content

​
API Keys

All API requests are authenticated using an API key passed in the X-API-Key header. 
curl https://api.cuttr.com/api/platform/v1/test \
  -H "X-API-Key: cuttr_a1b2c3d4e5f6..."

​
Creating keys

Create API keys from the dashboard or via the Create Key endpoint. Each key:
  • Is tied to a specific team
  • Can have an optional expiration date
  • Is shown in full once at creation — only the prefix (cuttr_a1b2...) is stored after that
  • Is hashed with SHA-256 before storage — we never store your raw key

​
Key lifecycle

StateDescription
ActiveKey is valid and can make requests
ExpiredPast its expires_at date — returns 401
RevokedPermanently disabled via dashboard or API — returns 401
Revoking a key is irreversible. If you suspect a key is compromised, revoke it immediately and create a new one.

​
Authentication flow

When you make a request, the API:
  1. Checks the X-API-Key header is present
  2. Hashes the key and looks it up in the database
  3. Verifies the key is not revoked or expired
  4. Checks that the team has an active billing account with sufficient balance
  5. Checks the per-key rate limit (60 requests/minute)
  6. If all checks pass, the request proceeds

​
Error responses

StatusErrorMeaning
401Missing X-API-Key headerNo key provided
401Invalid API keyKey not found or revoked
401API key expiredKey past expiration date
402Insufficient balanceWallet balance is zero — top up first
403API billing not activeTeam doesn’t have an active billing account
429Rate limit exceededToo many requests — check Retry-After header

​
Best practices

Use environment variables or a secrets manager. If a key leaks in a git commit, revoke it immediately.
Create different keys for development, staging, and production. This way you can revoke one without affecting others.
If you’re sharing a key with a contractor or for a demo, set an expiration so it auto-disables.
Check the usage logs to spot unusual patterns. Each log entry shows which key made the request.