Authentication

Client Credentials

The Pixelbase API uses 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 in the Dashboard under the Dev Tools page.

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.

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.

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"
    }
  }
}

Company and Personal Clients

There are two kinds of API client, and the difference is what bounds them.

A company client, created on /dev-tools, belongs to one company and holds the scopes you grant it. This is the right choice almost every time: it is scoped, it is bound to a single company, and revoking it affects nothing else.

A personal client, created in personal settings or through the agent handshake, acts as the person who owns it. It has no scope list to narrow — its ceiling is whatever permissions that account has in the company being acted on. Use it when something has to act as a person rather than as an integration.

Choosing a Company

A personal client's owner may work at more than one company, so requests say which one they mean with an X-Company-Id header. Omit it and the account's default company is used, or its only one if it has just a single employment; if neither applies the request is rejected rather than guessing. Company clients ignore this header — their company comes from the token.

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.