Get started
Authentication and keys
Every call carries a partner key in the Authorization header. The key says who you are, in which environment, and what you may do.
Sending the key#
GET /partner/v1/me HTTP/1.1
Host: <base address>
Authorization: Bearer lpk_test_…We keep only a SHA-256 hash of the key; it can never be shown again. If you lose it, ask for a new one.
OAuth 2.0 instead of the fixed key#
For systems that prefer OAuth: ask for an access token with client_credentials, where client_id is your key’s id (key.id of GET /partner/v1/me) and client_secret is the key itself, in a JSON or form body, or with HTTP Basic. You get a bearer token lpt_… valid for one hour (never past the key’s own end) with the key’s scopes; send it as Authorization: Bearer, exactly like the key.
curl -sS -u "$LP_KEY_ID:$LP_API_KEY" \
-d grant_type=client_credentials \
"$LP_BASE_URL/partner/v1/oauth/token"curl -sS -X POST "$LP_BASE_URL/partner/v1/oauth/token" \
-H "Content-Type: application/json" \
--data '{
"grant_type": "client_credentials",
"client_id": "key_01JD5ZC9",
"client_secret": "lpk_test_…"
}'{
"access_token": "lpt_…",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "branches:read catalog:read catalog:write availability:write orders:read orders:ack orders:status orders:cancel orders:events payments:read reports:read webhooks:manage mappings:write"
}- Revoking the key stops its tokens at once.
- A refusal carries its reason in
detail.error:invalid_client·unsupported_grant_type·invalid_request. - Fetch a new token a minute before expires_in runs out; never one per call.
Environments never mix#
| Prefix | Environment | Works on |
|---|---|---|
lpk_test_… | sandbox | The sandbox only |
lpk_live_… | live | Production only |
A key sent to the other environment is refused with 401 KEY_ENVIRONMENT_MISMATCH. A test configuration can never touch production by mistake. More on environments.
Scopes#
Each key carries a list of scopes. Read scopes never change anything; each write scope opens one family of calls. A call without the scope it needs is refused with 403 SCOPE_REQUIRED, and the scopes it needs are in detail.required.
| Scope | What it allows | Default for |
|---|---|---|
branches:read | Read the branches the key may act on: names, location, fulfilment, pause, and your code for each. | ERPPoint of sale (POS)Kitchen display (KDS)Delivery fleetOrdering marketplaceAccountingAnalyticsOther |
catalog:read | Read the published menu: categories, items, sizes, options and prices, with your codes for what is mapped. | ERPPoint of sale (POS)Kitchen display (KDS)Ordering marketplaceAnalytics |
catalog:write | Send the menu from your system (when it is the menu source). Saved as a draft or published per the publish policy. | ERP |
availability:write | Switch an item or option off at a branch when it runs out, and back on. Never clears a flag set by branch staff. | ERPPoint of sale (POS) |
orders:read | Read orders: new orders by pulling, and any order of your branches. | ERPPoint of sale (POS)Kitchen display (KDS)Delivery fleetAccountingAnalytics |
orders:ack | Acknowledge that an order reached your system, with your own number for it. | ERPPoint of sale (POS)Kitchen display (KDS) |
orders:status | Report order statuses (accepted, preparing, ready, out for delivery…) within the statuses allowed to you. | ERPPoint of sale (POS)Kitchen display (KDS)Delivery fleet |
orders:cancel | Ask to cancel an order: the customer called the branch, or the kitchen cannot make it. | ERPPoint of sale (POS) |
orders:events | Record facts on an order without moving it, such as a receipt issued or cash collected at the door. | ERPPoint of sale (POS)Delivery fleet |
payments:read | Read how an order is paid, what was collected and what was refunded. | ERPPoint of sale (POS)Accounting |
reports:read | Read the daily reconciliation reports: order counts and amounts per branch. | ERPAccountingAnalytics |
webhooks:manage | Manage your own webhook subscriptions: addresses, events and branches. | ERPPoint of sale (POS)Delivery fleetOrdering marketplaceAccounting |
mappings:write | Send the mapping between Let's Pizza ids and your system's codes (branches, items, options, tenders). | ERPPoint of sale (POS)Kitchen display (KDS) |
The last column is what a new key of each kind gets unless we choose otherwise. We issue keys with the fewest scopes your system needs.
Branches#
A key can be limited to some branches (up to 200). A null key.branches means every branch. A call about a branch outside the list is refused with 403 BRANCH_NOT_ALLOWED.
IP allowlist#
On request we limit a key to given IP addresses or CIDR blocks (up to 50 entries). Send us the fixed outbound addresses of your servers. A call from any other address is refused with 403 IP_NOT_ALLOWED. An empty list means anywhere.
Rate limits#
Each key has a number of requests per minute (between 10 and 6000), shown in key.ratePerMinute. Every authenticated answer carries:
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42Over the limit the answer is 429 RATE_LIMITED with Retry-After (also in detail.retryAfterSeconds). Wait that long, then retry; never retry at once.
Rotation and expiry#
A key may carry an end date (up to 730 days), in key.expiresAt. After it the key is refused with 401 KEY_EXPIRED.
Ask for a second key for the same environment.
Both keys work side by side: no downtime.Deploy the new key in your system.
Check with GET /partner/v1/me that key.id is the new one.Ask us to revoke the old key.
It stops at once; any call with it is refused with UNAUTHENTICATED.
Order of checks#
- A known, unrevoked key; else UNAUTHENTICATED (401).
- The key's environment is the host's; else KEY_ENVIRONMENT_MISMATCH (401).
- Not expired; else KEY_EXPIRED (401). The partner is active; else PARTNER_SUSPENDED (403).
- The address is in the allowlist, if any; else IP_NOT_ALLOWED (403).
- Within the rate; else RATE_LIMITED (429).
- Carries the call's scopes; else SCOPE_REQUIRED (403).