Authentication

All requests to the Circadify API require an API key. Keys are created in the developer portal and scoped to either test or live environments.

API Key Types

Circadify uses a single key system with two environments:

Key Type	Prefix	Purpose
Test	ck_test_	Development and testing. Connects to sandbox infrastructure.
Live	ck_live_	Production use. Connects to production infrastructure.

Both key types are 28+ character strings generated with cryptographically secure randomness:

ck_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4
ck_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6

Note

Test and live keys authenticate identically — the difference is which backend environment they route to. Use test keys during development to avoid consuming your production scan quota.

Creating Keys

1. Log in to developer.circadify.com
2. Navigate to Keys in the sidebar
3. Click Create Key
4. Enter a descriptive name and select the environment (Test or Live)
5. Copy the key immediately — it’s only shown once

The number of keys you can create depends on your plan:

Plan	Max API Keys
Starter	3
Pro	5
Enterprise	10

Using Your Key

API keys can be passed in either of two ways:

Authorization Header (recommended)

curl -X POST https://api.circadify.com/sdk/session/start \
  -H "Authorization: Bearer ck_live_your_key_here" \
  -H "Content-Type: application/json"

X-API-Key Header

curl -X POST https://api.circadify.com/sdk/session/start \
  -H "X-API-Key: ck_live_your_key_here" \
  -H "Content-Type: application/json"

In the Web SDK

Pass the key when initializing the SDK. The SDK handles all authentication automatically:

import { CircadifySDK } from '@circadify/sdk';

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
});

Caution

API keys used in client-side code (browser SDK) are visible to end users via browser dev tools. This is expected — the key is scoped to your account’s plan limits and rate limits. For server-to-server calls, keep keys in environment variables and never commit them to source control.

Rate Limits

Every API key is subject to rate limits based on your plan:

Plan	Requests / Hour	Monthly Scans
Starter	300	500
Pro	1,000	5,000
Enterprise	5,000	50,000

When you exceed the hourly rate limit, the API returns 429 Too Many Requests with a Retry-After header:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryable": true,
  "retryAfter": 42
}

When you exceed your monthly scan quota, the API returns 429 with error code QUOTA_EXCEEDED:

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly scan quota exceeded. Upgrade your plan at developer.circadify.com.",
  "retryable": false
}

Checking Usage

Monitor your usage via the developer portal Usage page or the API:

curl https://api.circadify.com/developer/usage \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

Response:

{
  "current_month": {
    "month": "2026-04",
    "scan_count": 127,
    "last_scan_at": 1743523200
  },
  "limit": 500,
  "remaining": 373,
  "plan": "starter"
}

Key Revocation

To revoke a key, go to the Keys page in the developer portal and delete it. Revocation is:

• Immediate — The key stops working within seconds
• Permanent — Revoked keys cannot be re-enabled; create a new one instead

You can also revoke via the API:

curl -X DELETE https://api.circadify.com/developer/keys/KEY_ID \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

Security

How keys are stored

Your API key is never stored in plaintext. On creation, the server computes a one-way hash of the key and stores only the hash and a short prefix (for display in the dashboard). The full key exists only in the creation response.

Lockout protection

If 10 consecutive failed authentication attempts are made with an invalid key from the same identifier within 15 minutes, further requests are temporarily blocked. This protects against brute-force key guessing.

Best practices

• Use environment variables — Store keys in .env files or your platform’s secret manager, not in source code.

  .env

  CIRCADIFY_API_KEY=ck_live_your_key_here

  const sdk = new CircadifySDK({
    apiKey: process.env.CIRCADIFY_API_KEY,
  });

• Use test keys for development — Avoid consuming production quota during development. Test keys have the same API surface.

• Create separate keys per environment — Use different keys for development, staging, and production so you can revoke one without affecting others.

• Rotate keys periodically — Create a new key, update your deployment, then revoke the old key. Both keys work simultaneously until you revoke.

• Never commit keys to git — Add .env to your .gitignore. If a key is accidentally committed, revoke it immediately and create a new one.

• Monitor usage — Check the Usage page regularly. Unexpected spikes may indicate a leaked key.

Error Responses

HTTP Status	Error Code	Meaning
401	API_KEY_INVALID	Key doesn’t exist or is malformed
401	API_KEY_REVOKED	Key has been revoked
401	API_KEY_EXPIRED	Key has passed its expiration date
403	DEVELOPER_SUSPENDED	Your account has been suspended
403	DEVELOPER_PENDING	Your account hasn’t been approved yet
429	RATE_LIMIT_EXCEEDED	Hourly request limit exceeded
429	QUOTA_EXCEEDED	Monthly scan limit exceeded

All error responses include a consistent JSON body:

{
  "error": "API_KEY_INVALID",
  "message": "The provided API key is not valid.",
  "retryable": false
}

Next Steps

• Quick Start — Install the SDK and run your first scan
• REST API Overview — Full API endpoint reference
• Rate Limits — Detailed rate limiting behavior
• Security Overview — Full security model