API
Authentication
How API clients, assistants and the CLI get an access token, and what bounds it.
Client Credentials
A server-side integration authenticates with the OAuth 2.0 client credentials grant. You create an API client to get a client_id and client_secret, then exchange those for a short-lived access token. Manage your clients under Dev Tools → API.
You don't need one for an assistant or the CLI: those sign in through your browser instead — see API clients and connected apps.
Your client secret carries many privileges, so be sure to keep it secure! Do not share it in publicly accessible areas such as GitHub, client-side code, and so forth. The client ID is not secret and can be retrieved at any time.
dev:api:write permission in your company.Getting an Access Token
Exchange your client credentials at the token endpoint. Send grant_type=client_credentials and, optionally, a space-delimited scope parameter (a subset of the scopes your client was granted). Credentials may be sent via HTTP Basic auth or in the form body.
curl -X POST https://www.pxb.app/api/public/v1/oauth/token \
-u "your_client_id:your_client_secret" \
-d "grant_type=client_credentials" \
-d "scope=locations:read customers:read"{
"access_token": "pxb_at_3f9c1e7b2a4d...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "locations:read customers:read"
}Authenticated Requests
Send the access token in the Authorization header using the Bearer scheme. For a company client the company is derived from the token, so no other headers are required.
AuthorizationSet to Bearer <access_token> using an access token obtained from the token endpoint. Tokens are short-lived — request a new one when it expires.curl https://www.pxb.app/api/public/v1/test-token \
-H "Authorization: Bearer your_access_token_here"{
"message": "Access token is valid",
"content": {
"client": {
"id": "e9b1f3a7-2c4e-4b3a-bb6f-1e2d3c4a5b6f",
"name": "Production",
"clientId": "pxb_client_abc12345"
},
"token": {
"id": "5a2c9f1d-7b3e-4c8a-9f0b-2d1e3c4a5b6f",
"tokenPrefix": "pxb_at_3f9c1e7b",
"scopes": [
"locations:read",
"customers:read"
],
"expiresAt": "2026-05-09T19:02:14.000Z",
"lastUsedAt": "2026-05-09T18:02:14.000Z"
}
}
}API Clients and Connected Apps
There are two ways to hold a token, and the difference is who approved it.
A company API client, created on /dev/api, belongs to one company and holds the scopes you grant it. It is the right choice for anything that runs unattended — a scheduled job, a server-side integration — and revoking it affects nothing else.
A connected app — an assistant over MCP, the pxb CLI, or any OAuth client — gets its token through the authorization-code flow with PKCE. The person signs in at /oauth/authorize and chooses which of their companies it may reach and what it may do in each; it then acts as them, never beyond what they hold. Discovery lives at /.well-known/oauth-authorization-server. Connections are managed under Dev Tools → MCP and Dev Tools → CLI.
Apps Without a Browser
An agent in a sandbox, or pxb auth --device over SSH, has no browser to send the person to. It uses the device authorization grant (RFC 8628) instead: it asks for a code, shows the person a link and a short code to enter on any device, and polls the token endpoint until they approve. Only apps that registered the urn:ietf:params:oauth:grant-type:device_code grant can start one. The tokens it collects are the same a connected app gets.
curl -X POST https://www.pxb.app/api/oauth/device-authorization \
-d client_id=your_client_id
# show the person verification_uri and user_code, then every `interval` seconds:
curl -X POST https://www.pxb.app/api/public/v1/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d client_id=your_client_id \
-d device_code=pxb_dc_...Until they decide, polling answers authorization_pending; poll faster than the interval and it answers slow_down and adds five seconds. access_denied and expired_token are final.
Choosing a Company
A connected app may reach more than one company, so its requests say which one they mean with an X-Company-Id header. Omit it and the account's default company is used, or the only one if it reaches just one; if neither applies the request is rejected rather than guessing. GET /me lists the companies a token can act in. Company clients ignore this header — their company comes from the token.
X-Company-IdThe company to act in. Required for a connected app that reaches several companies, when the account has no default among them.curl https://www.pxb.app/api/public/v1/orders \
-H "Authorization: Bearer your_access_token_here" \
-H "X-Company-Id: your_company_id"Security Best Practices
- Keep your client secret secret. Never expose it in client-side code, public repositories, or logs. Only the token endpoint should ever see it.
- Use environment variables. Store your client credentials in environment variables rather than hardcoding them.
- Cache and refresh tokens. Access tokens are short-lived — reuse a token until it nears expiry, then request a new one instead of minting one per request.
- Use separate clients for different environments. Have distinct clients for development, staging, and production.