Authentication

Every API request authenticates with an API key, sent as a bearer token:

GET /v1/me HTTP/1.1
Host: api.usa.dialerdigital.com
Authorization: Bearer dd_k3y…example-not-a-real-key

There is no separate login flow, no session cookies, no OAuth dance. The key is your account: it scopes every request to your data and nothing else (enforced by row-level security in the database, not by application code you have to trust).

Keys are hashed at rest

Dialer Digital stores only the SHA-256 of your key. Nobody — including us — can read a key back out of the database. If you lose a key, you rotate it; you never "recover" it.

Getting your key

Your first key is issued during onboarding by the Dialer Digital team. From then on you manage keys yourself through the API (or the dashboard, which uses the same key).

Managing keys

Method	Path	What it does
GET	/v1/api_keys	List keys: id, label, created_at, revoked_at. Never the key material.
POST	/v1/api_keys	Mint a key. The plaintext token is returned once — store it immediately.
DELETE	/v1/api_keys/{id}	Revoke. Immediate; the row is kept for your audit trail.

Full request/response shapes: API keys reference.

Minting a key

curl -s -X POST $API/v1/api_keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "warehouse-etl"}'

{
  "api_key": {
    "id": "7c0e6a1e-3f2b-4d5c-9e8f-1a2b3c4d5e6f",
    "label": "warehouse-etl",
    "revoked_at": null,
    "created_at": "2026-07-01T14:30:00Z"
  },
  "token": "dd_k3y…shown-exactly-once…"
}

Zero-downtime rotation

1. POST /v1/api_keys with a fresh label — you get the new plaintext token.
2. Deploy the new token to your integration and confirm it works (GET /v1/me).
3. DELETE /v1/api_keys/{old-id} — the old key stops working immediately, everywhere. Revocation also drops live WebSocket connections within one heartbeat.

Because you can hold several active keys, rotation never requires a maintenance window.

When authentication fails

Status	error.code	Meaning	What to do
401	unauthorized	Missing, malformed, unknown or revoked key.	Check the Authorization: Bearer header; mint/rotate if the key was revoked.
403	forbidden	The key is valid but the account is suspended.	Contact your account manager — no request will succeed until the account is reactivated.

A 401 never tells you which of those conditions applied — that is deliberate.

Best practices

• One key per integration, labeled ("crm-sync", "warehouse-etl", …), so revocation is surgical.
• Server-side only. Never ship a key in mobile apps, browsers or client-visible config.
• Rotate on your normal credential schedule, and immediately on staff departure or suspected exposure.
• Log X-Request-ID for failed calls — support can trace any request from it.