Authentication

All requests to the Circadify API require an API key. Keys are created in the developer portal.

API Keys

Circadify keys begin with ck_live_ followed by a cryptographically random string:

ck_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6

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
5. Copy the key immediately — it’s only shown once

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/web-sdk';

const sdk = new CircadifySDK({
  apiKey: 'ck_live_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 a per-plan hourly request rate limit. When you exceed the 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
}

See Rate Limits for details and per-plan thresholds.

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_DEVELOPER_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

Repeated failed authentication attempts with an invalid key from the same identifier 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,
  });

• 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

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