Skip to content

Authentication

The PlusPlus Public API uses bearer tokens. Every request must include an Authorization header:

Authorization: Bearer pp_your_token_here

Requests without a valid token receive 401 Unauthorized.

Token format

PlusPlus tokens are opaque strings prefixed with pp_. The prefix is informational; the rest is a securely generated random secret. Tokens are not JWTs — they cannot be decoded client-side.

Token scope

Each token inherits the role and permissions of the user who created it at the moment of creation. If a user's role changes later, existing tokens reflect the new role on their next request. Revoke and re-create tokens after role changes if you need a clean cutover.

In the preview release, tokens are not yet scoped to specific resources or operations. Granular scopes are on the roadmap.

Rotating tokens

To rotate a token:

  1. Create a new token in Settings → API tokens.
  2. Update the integration that uses the old token to use the new one.
  3. Revoke the old token.

You can run multiple active tokens at once, which makes zero-downtime rotations straightforward.

Revoking tokens

Revoke a token from Settings → API tokens by clicking Revoke next to it. Revocation is immediate — the token cannot be used again, and any in-flight requests using it will fail at next dispatch.

Common authentication errors

Status Code Cause
401 unauthenticated Missing or malformed Authorization header.
401 invalid_token Token does not exist, has been revoked, or belongs to a different tenant.
403 forbidden Token is valid but the underlying user lacks permission for this operation.

Every error response includes a request_id — quote it when contacting support. See Errors for the full envelope.