Authentication
Every authenticated request carries one header:
Authorization: Bearer <token>The API looks at the shape of the token and sends it to exactly one validator:
| Token | Shape | Where it comes from | Use it for |
|---|---|---|---|
| Session JWT | Three dot-separated segments | POST /api/v1/auth/login; short-lived, renewed with POST /api/v1/auth/refresh |
The Pitch2Sale web app |
| Personal access token | pat_ followed by 64 hex characters |
Settings → API keys, or the API keys endpoints | Integrations and scripts (recommended) |
| OAuth access token | 64 hex characters, no prefix | Issued to installed OAuth apps | Installed apps only |
A token that looks like a JWT but fails verification is rejected. It never falls back to the other validators, so a malformed token always fails the same way.
curl -H "Authorization: Bearer pat_…" "https://api.pitch2sale.com/api/v1/leads?limit=5"Never put a token in a URL, a browser bundle or a repository. Keep it in an environment variable or a secret manager on your server.
Who the request runs as
Section titled “Who the request runs as”A personal access token belongs to the user who created it and to that user’s organization. Requests made with it:
- see only that organization’s data;
- inherit the user’s role permissions — the key can do what the user can do, and no more;
- stop working when the key is revoked, the user is deactivated, or the organization is inactive or suspended.
Scopes on the key narrow this further on some endpoints; see API keys → Scopes.
Session-only endpoints
Section titled “Session-only endpoints”Endpoints that create credentials or change identities accept a session JWT only. A personal access token, an OAuth access token or an impersonated (“Login as”) session gets 403 {"error":"Forbidden"} on:
- creating and revoking API keys;
- registering and changing OAuth apps;
- creating, changing, deactivating and deleting users, resetting their passwords and changing their roles or permissions;
- creating, editing and deleting roles;
- the SCIM token and single sign-on settings;
- “Login as” impersonation.
Integrations should read and write CRM data with a key, and leave user and access management to a person signed in to the app.
Two more rules apply to these endpoints, whatever the credential. Only the organization owner or a system administrator can reset the password of, change the role, permissions, manager or status of, or create an Admin-level user, or manage the SCIM token and single sign-on. Nobody can grant a role, override or permission they do not hold themselves. Refusals are a bare 403 {"error":"Forbidden"}.
Impersonation
Section titled “Impersonation”A system administrator can sign in as another user with “Login as”. The resulting session lasts 1 hour, its tokens record who started it, and each impersonation is written to the audit log. The organization owner and other system administrators cannot be impersonated.
Authentication failures (401)
Section titled “Authentication failures (401)”| Body | Meaning |
|---|---|
{"error":"Authentication required"} |
No Authorization header, or it does not start with Bearer . |
{"error":"Invalid or expired token"} |
A personal access token or OAuth token that is unknown, revoked or belongs to an inactive user. |
{"error":"Token expired"} |
A session JWT past its expiry. Refresh it. |
{"error":"Invalid token"} |
A JWT-shaped token that fails signature verification. |
A personal access token for an organization that is inactive or suspended gets 403 {"error":"Organization is inactive"}.
Permission and plan failures
Section titled “Permission and plan failures”Authentication only proves who you are. Each endpoint then checks up to three more things:
-
Role permission (403). The endpoint requires a permission such as
leads.create. If the user’s role lacks it:{ "error": "Forbidden", "required_permission": "leads.create" } -
Plan feature (402). Some endpoints belong to a feature that the organization’s plan must include:
{ "error": "plan_upgrade_required", "feature": "settings.webhooks", "current_plan": "starter" }errorisfeature_disabledinstead when the feature has been switched off for the organization. -
Token scope (403). On endpoints that check scopes, a key without the required scope gets
{"error":"Token does not have required scope: write:leads"}.
See Errors for the full envelope.