Authentication

The Dolores REST API authenticates every request with a bearer API key. Keys are project-scoped — one key only grants access to one project's customers, appointments, sessions, events, and webhook endpoints.

Creating keys

Open Settings → API Keys in the admin UI and click + Create key.

Two modes are available:

The plaintext key is shown once on creation. Dolores stores only a SHA-256 hash — we cannot recover the plaintext if you lose it. Treat it like a password.

Sending the key

Include the key in the Authorization header on every request:

GET /v1/customers HTTP/1.1
Host: app.meetdolores.ai
Authorization: Bearer sk_live_8fK2xPv...

curl https://app.meetdolores.ai/v1/customers \
  -H "Authorization: Bearer $DOLORES_API_KEY"

Missing or malformed authorization headers return 401 invalid_api_key:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Missing API key. Include \"Authorization: Bearer sk_...\" on every request.",
    "request_id": "req_01HXY..."
  }
}

Livemode flag

Every key has a livemode boolean baked in. The flag propagates into:

• Resources you create — every customer, appointment, session, event has livemode: true|false.
• Webhook endpoints — endpoints are tagged at creation and only receive deliveries with matching livemode.

Test-mode resources never count against billing, never dial real phones, and never appear in your live dashboards.

Rotation

Rotate keys regularly and after any suspected leak:

1. Settings → API Keys → + Create key with a label like "rotated 2026-06-01".
2. Deploy the new key to your backend.
3. Verify traffic is flowing on the new key via the last_used_at timestamp on each row.
4. Revoke the old key. Requests using it start returning 401 immediately.

There's no warm-up period — revocation is instant.

Security best practices

• Never commit keys to source control. Use environment variables or a secret manager.
• Use test keys in CI. They can't dial real phones or charge customers, so leaked test keys have a much smaller blast radius.
• Rotate quarterly, at minimum. Set a calendar reminder.
• One key per service. If you have a backend, a worker, and a CLI tool, each gets its own labelled key. Revoking one service's key shouldn't take the others down.
• Watch last_used_at. Keys that haven't been used in 90+ days are candidates for revocation.