Authentication

Bearer keys

Every request carries the key in a standard HTTP Bearer header:

Authorization: Bearer mip_live_...

There is no OAuth flow, no session, and no cookie. A missing or unrecognized key returns 401 with error_code: "invalid_key".

Key format

Keys are mip_live_ followed by 48 random base62 characters. Keys are never stored in recoverable form — only a peppered hash is persisted — so a lost key must be rotated, not recovered.

Scopes

Scopes are colon-formatted and granted per key: customers:read, leads:write, webhooks:manage, communications:send, and so on. A call to a route your key isn't scoped for returns 403 with missing_scope.

Grant the narrowest scope set that does the job. A reporting integration should hold only *:read scopes — read-only keys skip request signing, with two exceptions: communications:read and audit_log:read expose broad, sensitive data, so a key holding either must sign every request, exactly like a write-capable key. See Request Signing.

Company keys vs. branch keys

• Company-scoped keys see every branch in the company.
• Branch-scoped keys are hard-filtered to one branch_id at the gateway — the filter is not something the caller can widen.

Two caveats before you pick branch-scoped:

• Six resources are company-wide only. Storage, inventory, tasks, claims, employees, and the audit log carry no per-record branch attribution, so a branch-scoped key calling those routes gets 403 branch_scope_unsupported rather than a misleading empty list. Use a company-wide key for those.
• Branch-scoped keys never see unbranched records. Records that never got a branch assigned have no branch attribution, and a branch-scoped key cannot see them. If you're doing a full-tenant sync, use a company-wide key — a branch key's view is "this branch's records," not "everything except other branches."

Rotation

The Rotate action swaps the key material atomically: a new key (and a new signing secret, if the key signs) is shown once, and the old credential stops working immediately. Rotate on any suspicion of exposure.

If you need zero-downtime rotation on a schedule, use create-then-revoke instead: mint a replacement key, deploy it, then revoke the old one. A company can hold many keys at once, so there's no forced downtime window.

Every mint, rotate, and revoke is written to the audit log and notifies Owners and admins with key-management permission.

IP allowlists

Each key can optionally carry an IP allowlist. Requests from outside the list are rejected with 403 ip_not_allowed. If your integration runs on infrastructure with stable egress IPs, turn this on.

Key handling rules

• Keys belong on a server. Never ship one in a browser bundle, mobile app, or public repository.
• Store keys in your platform's secret manager, not in source control or environment files that get committed.
• Use one key per integration so you can revoke a single consumer without disrupting the others.
• If a key may have leaked, revoke it first and investigate afterward.