Authentication, keys and scopes

Every request sends a credential in the Authorization header:

Authorization: Bearer lmk_0123456789abcdef0123456789abcdef0123456789abcdef

A credential sent anywhere else (for example ?key= or ?access_token= in the address) is refused with 400, so it never ends up in logs.

Two kinds of credentials

	API key	Partner app token
Who	A pro, for their own tools	A software company, for many pros
Looks like	`lmk_` + 48 hex	`lmo_` + 48 hex (access), `lmr_` + 48 hex (refresh)
Made in	My account, Settings, Connect your software	The pro taps Allow on our Connect screen
Lasts	90 days	1 hour (refresh tokens 180 days, rotated on use)
Access	Read only, or full	The scopes the pro allowed
Rate limit	600 requests an hour per business, shared by its keys	Sandbox 600, verified 3,000 an hour, per app per pro

Keys

Only an approved pro can make keys. Up to 5 active at a time; give each tool its own.
Let it make changes on gives full access. Off gives a read-only key: it reads everything and changes nothing (writes get 403 with insufficient_scope).
The Settings card shows each key's expiry and last use. Turn a key off with its switch; it stays off.
We keep only a SHA-256 hash of each key. We cannot show or recover a key.

Scopes

Every scope here can be granted. A full-access key has all of them; a read-only key has every :read scope.

Scope	Lets you
`leads:read`	List and read leads, lookups, customers, timeline
`leads:write`	Accept, decline, set status, job total, paid amount, external ids, notes, follow-up dates
`messages:read`	Read customer messages
`messages:write`	Send customer messages
`billing:read`	Charges and credits
`billing:write`	Ask for a credit on a lead
`reviews:read`	Reviews
`business:read`	Business profile, license, insurance, settings
`business:write`	Pause and resume, ZIP codes, highest lead price
`metrics:read`	Metrics
`webhooks:read`	Webhook delivery log
`webhooks:write`	Redeliver and replay webhook events

A call without the needed scope returns 403:

{"error":"This key or token does not have the billing:read scope","code":"insufficient_scope"}

What a credential can see

Only the business it belongs to. Customer contact details appear only after the lead is accepted (or a shared lead is sent), and only the way the customer chose: phone (name, phone, email if given), email (name and email), or in-app messages (name only).

Keep credentials safe

Store them on a server or in the tool's secure settings, never in website code, a shared spreadsheet, a chat or an email. If one may be exposed, turn it off (keys) or disconnect the app (tokens) and make a new one.