Authentication

API Keys

The Cara API uses API keys for authentication. Each key is scoped to your tenant and has one of two modes:

Getting your keys

1. Log in to the Cara platform.
2. Navigate to Settings → API Keys (or use the Credentials page in these docs).
3. Click Create API Key and choose test or live mode.
4. Copy the key immediately — it is only shown once.

Using your key

Include your API key in the Authorization header as a Bearer token:

curl -X GET https://platform.caramedical.com/api/v1/patients \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json"

const response = await fetch('https://platform.caramedical.com/api/v1/patients', {
  headers: {
    'Authorization': 'Bearer sk_live_your_key_here',
    'Content-Type': 'application/json',
  },
});
 
const data = await response.json();

import requests
 
response = requests.get(
    'https://platform.caramedical.com/api/v1/patients',
    headers={
        'Authorization': 'Bearer sk_live_your_key_here',
        'Content-Type': 'application/json',
    },
)
 
data = response.json()

Key scopes

API keys can be scoped to specific resources:

• patients:read — Read patient data
• patients:write — Create and update patients
• forms:read — Read form templates and submissions
• forms:write — Create and manage forms
• scheduling:read — View appointments and availability
• scheduling:write — Book and manage appointments
• emails:read — View email templates and sequences
• emails:write — Send emails and manage sequences

Rate limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Revoking keys

You can revoke API keys at any time from the platform settings or the Credentials page. Revoked keys immediately stop working.