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

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.