Authenticate with API keys

Every request needs a key. An API key from the dashboard works on one business, and a platform key works on many. Owners and admins create and revoke API keys in the dashboard. API keys, but not platform keys, also connect AI assistants through the MCP server.

Create a key

Open API keys

Go to Settings > API keys. Only owners and admins see the page.

Name the key and pick its access

Use a name you’ll recognize later, such as Zapier. Select only the scopes the tool needs.

Copy the key

LobbyStack shows the full key once. Store it in your tool or a password manager. LobbyStack keeps only a hash, so nobody can show the key again.

Keys look like lsk_1a2b3c4d_ followed by 32 random characters. The dashboard lists each key by name, with who created it and when it was last used.

Send the key

Put the key in the Authorization header:

curl https://app.lobbystack.com/api/v1/calls \
  -H "Authorization: Bearer $LOBBYSTACK_API_KEY"

A missing, unknown or revoked key returns 401 with the code unauthorized.

Test a key

GET /me works with any valid key, whatever its scopes. It returns the key and its business, so an integration can check a connection before it needs a specific scope:

{
  "data": {
    "api_key": {
      "id": "0b7c1d2e-3f40-4a51-8b62-7c83d94ea5b6",
      "name": "Zapier",
      "prefix": "lsk_1a2b3c4d",
      "scopes": ["appointments:read", "appointments:write"],
      "created_at": "2026-09-27T16:58:00.000Z"
    },
    "business": { "id": "75795511-9ee2-4cb2-a89d-f173ec1dd82d", "name": "Maple Salon" }
  }
}

Scopes

Each endpoint except GET /me requires one scope. A key without it gets 403 with the code insufficient_scope, and the message names the missing scope.

Scope	Allows
`business:read`	`GET /business`, `GET /services`, `GET /staff`, `GET /receptionist`, `GET /rules`, `GET /onboarding`, `GET /widget-keys`, `GET /calendars`, `GET /calendars/{connection_id}/calendars`, `GET /notification-preferences`
`business:write`	`PATCH /business`, `PATCH /receptionist`, `POST /services`, `PATCH` and `DELETE` on `/services/{service_id}`, `POST /rules`, `PATCH` and `DELETE` on `/rules/{rule_id}`, `POST /rules/reorder`, `PATCH /onboarding`, `POST /onboarding/complete`, `POST /widget-keys`, `PATCH /widget-keys/{widget_key_id}`, `POST /calendars/google/connect`, `POST /calendars/calcom/connect`, `POST /calendars/calendly/connect`, `PATCH` and `DELETE` on `/calendars/{connection_id}`, `PATCH /notification-preferences`
`calls:read`	`GET /calls`, `GET /calls/{call_id}`
`contacts:read`	`GET /contacts`, `GET /contacts/{contact_id}`
`contacts:write`	`POST /contacts`, `PATCH /contacts/{contact_id}`, `POST /contacts/passcodes`, `POST /contacts/passcodes/generate`
`appointments:read`	`GET /appointments`, `GET /appointments/{appointment_id}`, `GET /availability`
`appointments:write`	`POST /appointments`, `POST /appointments/{appointment_id}/cancel`, `POST /appointments/{appointment_id}/reschedule`
`messages:read`	`GET /messages`
`knowledge:read`	`GET /knowledge`, `GET /knowledge/{entry_id}`, `GET /knowledge/sources`, `GET /knowledge/sources/{source_id}`
`knowledge:write`	`POST /knowledge`, `PATCH` and `DELETE` on `/knowledge/{entry_id}`, `POST /knowledge/sources`, `PATCH` and `DELETE` on `/knowledge/sources/{source_id}`, `POST /knowledge/sources/{source_id}/expand`, `/retry` and `/cancel`, `POST /knowledge/uploads` and `POST /knowledge/uploads/{upload_id}/complete`
`billing:manage`	`GET` and `PATCH /billing`, `POST /billing/checkout`, `GET /billing/checkout/{checkout_id}` and, with a platform key that has access to every business, `POST` and `DELETE /billing/managed-plan`
`phone_numbers:manage`	`GET /phone-numbers`, `POST /phone-numbers/search`, `POST /phone-numbers/claims`, `GET /phone-numbers/claims/{claim_id}`, `DELETE /phone-numbers/{phone_number_id}` and `POST /phone-numbers/{phone_number_id}/replace`
`phone_numbers:purchase`	Only for a partner’s platform key, with `phone_numbers:manage`: `POST /phone-numbers/search`, `POST /phone-numbers/claims`, `POST /phone-numbers/{phone_number_id}/replace`
`team:manage`	`GET /team`, `POST /team/invitations`, `DELETE /team/invitations/{invitation_id}`, `PATCH` and `DELETE` on `/team/members/{membership_id}`, `POST /team/claim-link`
`webhooks:manage`	`GET`, `POST`, `PATCH` and `DELETE` on `/webhooks`, and `POST /webhooks/{webhook_id}/test`

To subscribe an endpoint to an event or change its URL, your key also needs the event’s read scope. For example, call.completed needs calls:read, and the events table lists the rest.

Platform keys

A platform key (lsp_...) onboards and manages many businesses, where an API key works on one. You can use one to set up the businesses you serve, for example with lobbystack onboard. A partner makes its own platform keys in its partner console. The host, whoever runs the deployment, sets the rest in PLATFORM_API_KEYS.

Make a partner’s platform key

Open API keys

In the partner console, go to API keys. Only the partner’s owners and admins can make and revoke keys.

Name the key and pick its access

Select only the scopes the tool needs. POST /businesses needs businesses:create, and POST /users needs users:create.

Copy the key

The console shows the full key once. LobbyStack keeps only a hash, so nobody can show the key again.

A partner’s key acts as the partner, so it keeps working when the person who made it leaves the team. Its billing scopes are the exception: see Partner endpoints. It reaches the partner’s active businesses, including the ones the console created, and no others. With the partner scopes, it also runs the partner itself through the Partner endpoints. It can’t start a Polar checkout for a business, set a managed plan or create a claim link. It can’t read or change alert preferences, because those act as a person. POST /businesses with a partner’s key creates a business of the partner, with no owner yet. Name the owner in owner_email, and the partner emails them an invitation to sign in on its dashboard. access_level sets what the business’s own team can use: full, the default, or activity. template_id starts the business from one of the partner’s templates and needs partner:read too. package_id sells it one of the partner’s packages and needs partner.businesses:write too. Without the scope, the request returns 403 with the code insufficient_scope. A partner’s platform keys can create 30 businesses an hour between them. The invitations it sends through POST /team/invitations and POST /users come from the partner and link to its dashboard. Leave owner_email out for a business the partner runs itself. Nobody gets an invitation, and a key can’t invite an owner later, so the business can’t be released. package_id then returns 400, because its checkout opens from the owner’s invitation. With phone_numbers:manage and phone_numbers:purchase, a partner’s key searches for, claims and replaces numbers as itself. On a deployment that bills tiers, this needs a paid tier, and Free returns 409. A key can claim only an offer it searched for, and it never gets a trial offer. The partner’s keys share 20 searches in 10 minutes. The links the API returns for a partner’s business, such as a widget’s script tag or a calendar connect link, point at the partner’s dashboard too.

Partner endpoints

The endpoints under /partner do what the partner console does. They read the partner, run its demos, packages, brand, domain, templates and team, and manage its Stripe account and tier. Only a partner’s key can call them, and it sends no LobbyStack-Business header. An API key or a host’s key gets 403 with the code forbidden. A key acts with an admin’s rights, so it never changes an owner. Inviting an owner, changing an owner’s role or removing one returns 403: do those in the console. Only owners can grant partner.billing:read and partner.billing:write, since those reach what only owners see in the console. partner.billing:write includes what partner.billing:read allows. The billing scopes work only while the owner who granted them is still an owner: the owner who created the key with them, or the owner who last updated the key with them. Once that person becomes an admin or leaves the team, the key’s billing requests return 409 with the code key_owner_inactive, and its other scopes keep working. POST /partner/billing/checkout makes the tier checkout out to that owner.

Scope	Allows
`partner:read`	`GET /partner`, `GET /partner/brand`, `GET /partner/domain`, `GET /partner/demos`, `GET /partner/demos/{demo_id}`, `GET /partner/packages`, `GET /partner/templates`, `GET /partner/team`, `GET /partner/businesses/{business_id}/billing`
`partner.businesses:write`	`POST /partner/businesses/{business_id}/release`, `DELETE /partner/businesses/{business_id}`, `PATCH /partner/businesses/{business_id}/billing`
`partner.demos:write`	`POST /partner/demos`, `POST /partner/demos/{demo_id}/publish`, `/rotate` and `/revoke`, `DELETE /partner/demos/{demo_id}`
`partner.packages:write`	`POST /partner/packages`, `PATCH` and `DELETE` on `/partner/packages/{package_id}`
`partner.branding:write`	`PATCH /partner/brand`, `POST` and `DELETE` on `/partner/domain`
`partner.templates:write`	`POST /partner/templates`, `DELETE /partner/templates/{template_id}`
`partner.team:write`	`POST /partner/team/invitations`, `DELETE /partner/team/invitations/{invitation_id}`, `PATCH` and `DELETE` on `/partner/team/members/{member_id}`
`partner.billing:read`	`GET /partner/stripe`, `GET /partner/billing`, `GET /partner/billing/checkout/{checkout_id}`, and `pool` in `GET /partner`. `partner.billing:write` allows these too.
`partner.billing:write`	`POST /partner/stripe/onboarding-link`, `PATCH /partner/billing/overage`, `POST /partner/billing/checkout`

POST /partner/team/invitations requires an Idempotency-Key, and POST /partner/packages, POST /partner/templates and POST /partner/billing/checkout take one. POST /partner/demos and POST /partner/demos/{demo_id}/rotate ignore it, so LobbyStack never stores a copy of a demo’s link. After a network error, check GET /partner/demos before you retry. PATCH /partner/brand takes a logo or favicon in base64, as the console uploads it.

Make a host’s key

The dashboard has no page for the host’s keys. On a self-hosted deployment, pnpm platform-key:create writes a new key to .platform-keys/<prefix>.json and prints its entry for PLATFORM_API_KEYS. Each entry sets:

The group the key belongs to (group; pass --group). Keys in the same group reach the same businesses.
The verified LobbyStack account the key acts as (owner_email), which owns the businesses the key creates.
Whether the key reaches every business ("access": "all"; pass --access all) or, by default, only the ones its group’s keys onboarded ("access": "group").
Its scopes. Unless you name some, a new key gets the scopes an API key can hold. POST /businesses needs businesses:create and POST /users needs users:create. Only platform keys can hold these two, and a new key gets them only when you pass --create-businesses or --create-users. GET /businesses needs business:read. The command refuses the partner scopes, because a host’s key has no partner to act on.

Older entries call the group partner and may set "access": "partner". Both still work, and the key reaches the same businesses. To update one, change partner to group and "access": "partner" to "access": "group". Update the admin first: older versions refuse group. The admin refuses an entry that sets both partner and group, and with it every key in PLATFORM_API_KEYS.

A key with "access": "all" acts as its owner_email account on every business on the deployment, without being on any team, and can read and change all of them. That key, and that account with its password, sessions and email inbox, are root credentials. Give them to as few people as you can, keep the account’s password as safe as the database’s, and remove the key’s entry from PLATFORM_API_KEYS if either leaks. pnpm platform-key:create --access all prints the same warning.

Once the admin restarts without a key’s entry in PLATFORM_API_KEYS, requests with that key fail, and LobbyStack turns off the webhook endpoints the key created. To keep one, turn it back on with another of your platform keys.

Use a platform key

POST /businesses creates a business. GET /businesses lists the ones the key’s group onboarded, or for a partner’s key, every business of the partner. Every other request names its business in the LobbyStack-Business header:

curl https://app.lobbystack.com/api/v1/services \
  -H "Authorization: Bearer $LOBBYSTACK_PLATFORM_KEY" \
  -H "LobbyStack-Business: 75795511-9ee2-4cb2-a89d-f173ec1dd82d"

Without the header, the request returns 400 with the code business_required. A business the key can’t reach returns 404. GET /me works without the header and shows the key’s group and reach in platform. platform.reach is group for a key with group access and all for a key that reaches every business. API v1 keeps the older names as well: platform.partner repeats platform.group, and platform.access repeats platform.reach but reads partner for group access. For a partner’s key, platform.partner_id names the partner, which is also the key’s group. It’s null for the host’s keys. POST /team/claim-link hands a business to its owner. Once they accept, a key with group access no longer reaches it, and a key with access to every business still does. Either way, GET /businesses stops listing it. LobbyStack also turns off the business’s webhook endpoints that a platform key, the account that sent the link, or that account’s API keys created. A partner’s business stays with the partner, so POST /team/claim-link returns 409 for one. Only the partner can release it to its owner. Only a verified LobbyStack account can accept a claim link, and the link’s page lets an owner without an account sign up first. To invite them ahead of it, POST /users emails the address a sign-up link, or a sign-in link if the address already has an account. It never makes an account, so the owner signs up with their own password or with Google, and it answers the same either way, so you can’t tell who has an account. A platform key can invite 50 addresses a day.

Update a key

On Settings > API keys, click Update next to the key to change its name or scopes, then Save. The key stays the same, and requests with it get the new scopes right away. You can’t update a revoked key. On the partner console’s API keys page, only owners can update a platform key that has billing access.

Revoke a key

On Settings > API keys, click Revoke next to the key. Requests with it fail right away, and you can’t undo it. Create a new key if you still need access. LobbyStack also turns off the webhook endpoints the key created. To keep one, turn it back on in Settings > Webhooks. To revoke a partner’s platform key, click Revoke next to it on the partner console’s API keys page. Requests with it fail right away. LobbyStack turns off the webhook endpoints the key created on every business, and revokes the invitations the key sent, to a business’s team or to the partner’s, that nobody has accepted. Owners the key invited when it created their business can still accept.

Rate limits

Each key can make 120 requests per minute. Self-hosted deployments can change this with PUBLIC_API_RATE_LIMIT_PER_MINUTE. The window resets at the start of each minute. Every response carries these headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute.
`X-RateLimit-Remaining`	Requests left in the current minute.
`X-RateLimit-Reset`	Unix time, in seconds, when the window resets.

Past the limit, the API returns 429 with the code rate_limited and a Retry-After header with the seconds to wait.

Keep keys safe

Use one key per tool so you can revoke one without breaking the others.
Give each key the fewest scopes that work.
Never put a key in browser code or a mobile app. Call the API from a server.
LobbyStack logs each request with the key’s ID, never the key itself, and records changes made with a key in the business’s audit log.

Get started

General

Agents

Settings

White label

API

AI assistants

API reference

Self-hosting

Authenticate with API keys

Create a key

Send the key

Test a key

Scopes

Platform keys

Make a partner’s platform key

Partner endpoints

Make a host’s key

Use a platform key

Update a key

Revoke a key

Rate limits

Keep keys safe

​Create a key

​Send the key

​Test a key

​Scopes

​Platform keys

​Make a partner’s platform key

​Partner endpoints

​Make a host’s key

​Use a platform key

​Update a key

​Revoke a key

​Rate limits

​Keep keys safe

Create a key

Send the key

Test a key

Scopes

Platform keys

Make a partner’s platform key

Partner endpoints

Make a host’s key

Use a platform key

Update a key

Revoke a key

Rate limits

Keep keys safe