LeadRails

Authentication

Every call to the v1 REST API is authenticated with a single workspace-scoped API key, sent as a bearer token. This page covers how keys are shaped, created, rotated, and revoked.

The bearer token

Send your key in the Authorization header on every request: 

curl -s https://api.leadrails.dev/v1/me \
  -H "Authorization: Bearer lr_live_yourkeyhere"

A missing, malformed, or unknown key returns 401 with the invalid-api-key problem type. The cheapest way to confirm a key works is GET /v1/me, which echoes your workspace identity and plan.

Key prefix scheme

Keys carry a prefix so they're recognizable in logs and so secret scanners can flag a leaked key on sight.

Prefix Meaning
lr_live_ A live key. Authorizes real calls against your workspace.
lr_test_ Reserved for a future test-mode tier. Not yet shipped — a key with this prefix returns 501 with the test-mode-not-available problem type. Don't build against it yet.

Creating a key (shown once)

Create keys from the dashboard at Settings → API keys:

  1. Click Create key and give it a memorable name (e.g. "local-dev", "ci").
  2. Copy the full lr_live_… value immediately. It is shown exactly once. We store only a hash — there is no endpoint and no dashboard view that can reveal the plaintext again.
  3. Store it in your secret manager. Never commit it; never expose it to a browser.

If you lose a key, you don't recover it — you create a new one and revoke the old one (below).

Rotation

Keys don't expire on a clock; rotate them on your own schedule (and immediately on any suspected leak). The zero-downtime procedure:

  1. Create a new key in Settings → API keys.
  2. Deploy the new key to your services. Both keys are valid at this point.
  3. Confirm traffic has moved to the new key.
  4. Revoke the old key.

Because keys are workspace-scoped (not user-scoped), a rotated key keeps working against any in-flight idempotency replays — see Idempotency for why replays survive a key change within the same workspace.

Revocation

Revoke a key from the dashboard. Revocation takes effect immediately: the next request that key makes gets a 401 invalid-api-key. Revocation is permanent — a revoked key is never reactivated.

Workspace scoping

An API key authorizes exactly one workspace. Every resource it creates or reads belongs to that workspace, and any reference to a resource ID from a different workspace resolves as if it does not exist:

  • Reading a sibling workspace's resource returns 404 not-found, never 403 — surfacing a 403 would leak that the row exists somewhere.
  • A POST/PATCH body that references a cross-workspace ID returns 400 invalid-reference.

Future: scoped keys

Today every key carries full access to its workspace (scopes: ["*"]). The key storage shape is already forward-compatible with finer scopes — e.g. destinations:write, events:read — so a future release can issue least-privilege keys without a breaking change. Until that ships, treat every live key as full-access and scope it by what services hold it.

What's next

  • Quickstart — create a key and fire your first event.
  • Rate limits — per-key budgets and the headers that report them.
  • Idempotency — safe retries on every POST/PATCH.
  • HMAC signing — the separate per-source auth used by the intake surface (not bearer keys).