Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pickupbell.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Token format

PickupBell API tokens are UUIDv4 strings — 36 characters of hex with dashes. A token looks like: 
550e8400-e29b-41d4-a716-446655440000
We never store the raw token. On creation, only a SHA-256 hash goes into the database; the plaintext is shown once and cannot be recovered. The key_prefix column keeps the first 8 characters (550e8400) so the Keys UI can label a key without exposing the secret.

​
Using a token

Every authenticated request sends an Authorization header: 
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
No cookies, no query parameters. The MCP server uses the same header.

​
Scoping

A key carries zero or more scopes that authorize specific capabilities. Scopes are checked on every request by the service layer — if the key lacks the scope for the operation, you get 403 Forbidden with error.code = "forbidden" and a message naming the missing scope. See Scopes for the full list. General principles:
  • Least-privilege. Start with only what you need. You can mint a second key with different scopes rather than giving one key the union.
  • Read vs. write are split. :read scopes never grant writes.
  • Billing is never exposed. API tokens cannot read or modify subscriptions, invoices, or payment methods regardless of scope. Use the dashboard.

​
Location scoping

Tokens are location-scoped, not account-scoped. If a user owns three locations, they mint three tokens — one per location. An API key cannot cross location boundaries even if given an overly broad scope. Inside the token lifetime, you’ll only ever see one location when you call GET /api/v1/locations: 
curl https://api.pickupbell.com/api/v1/locations \
  -H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000"
# → { "data": [ { "id": "…", "slug": "premier-hvac", … } ] }

​
Rotating

  1. Mint a new key in the dashboard with the same scope set.
  2. Deploy it to your integration.
  3. Revoke the old key — any request using the revoked key returns 401 Unauthorized from the next second onward.

​
Common errors

Statuserror.codeMeaning
401unauthorizedMissing, malformed, or revoked Bearer token.
403forbiddenToken is valid but lacks the scope for this operation.
404not_foundResource doesn’t exist — or belongs to a location you don’t have access to.
For the full error model see Errors.