Authentication

API key types (live & sandbox), how to use them, and security best practices.

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

API Keys

Circadify issues two kinds of keys, distinguished by their prefix:

ck_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6   # production — real measurements, counts against your plan
ck_test_a1b2c3d4e5f6a7b8c9d0e1f2a3b4   # sandbox — simulated vitals, free, never billed

The prefix — not any header or SDK setting — determines behavior on the server, so a key always behaves the same wherever it's used.

Test (sandbox) keys

A test key (ck_test_) is a free, instant sandbox for building and testing your integration:

• Simulated vitals — scans return deterministic, physiologically-plausible vitals without running the measurement model. The result shape is identical to production, so your parsing code doesn't change.
• No quota, no billing — test scans never count against your monthly quota and are never billed.
• Same flow — the session lifecycle (start → upload → result) is identical to production, so the SDK works unchanged.

Create one from the Keys page in the developer portal by choosing the Test environment. In the React SDK, set environment="sandbox" to route to api.sandbox.circadify.com — optional, since a ck_test_ key returns simulated vitals against either host:

<CircadifyProvider apiKey="ck_test_your_key_here" environment="sandbox">

Use test keys for development, CI, and demos; switch to a ck_live_ key for real measurements in production.

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',
});

Rate Limits & Quotas

Sandbox (ck_test_) traffic is rate-limited on a best-effort basis to keep the free tier healthy. When a limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded",
  "retryable": true
}

Production (ck_live_) scan volume is governed by your plan's monthly scan quota rather than a request-rate limit. When you reach your quota, POST /sdk/session/start returns 429 QUOTA_EXCEEDED. Track usage on the Usage page in the developer portal.

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.

Brute-force resistance

API keys carry ~160 bits of entropy, so guessing a valid key is computationally infeasible. Keys are validated by hashing the full key and looking up the hash, and every authentication failure returns the same generic API_KEY_INVALID response to prevent enumeration.

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

  bash

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

  typescript

• Create separate keys per environment — Use a test key (ck_test_) for development and CI and a live key (ck_live_) for production, so you can revoke one without affecting the other. Test keys return simulated vitals and never bill.

• 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

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