API keys
A personal access token (PAT) is the recommended credential for integrations. It looks like pat_ followed by 64 hex characters and acts as the user who created it (see Authentication).
Create a key
Section titled “Create a key”In the app: Settings → API keys → create. Your role needs the settings.api_keys.create permission.
With the API, authenticated with a session JWT of the user who will own the key. Key management is session-only: a request authenticated with a personal access token, an OAuth access token or an impersonated (“Login as”) session gets 403 {"error":"Forbidden"}, so a leaked key cannot mint more keys.
curl -X POST "https://api.pitch2sale.com/api/v1/settings/api-keys" \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{ "label": "Warehouse sync", "scopes": ["read:leads", "read:opportunities"] }'label is required (1–100 characters). The label must be unique among your keys, revoked ones included; a duplicate returns 409. scopes is optional; see Scopes. Each requested scope must be backed by your role permissions, otherwise the request fails with 400 {"error":"Requested scopes exceed your permissions"}. The response is 201:
{ "key": { "id": "…", "label": "Warehouse sync", "token_prefix": "pat_…", "scopes": ["read:leads", "read:opportunities"], "last_used_at": null, "revoked_at": null, "created_at": "…", "updated_at": "…" }, "plain_token": "pat_…"}plain_token appears in this response only. Pitch2Sale stores a SHA-256 hash of it, so it cannot be shown again. Store it in your secret manager straight away; if you lose it, create a new key.
List your keys
Section titled “List your keys”curl -H "Authorization: Bearer <token>" "https://api.pitch2sale.com/api/v1/settings/api-keys"Returns { "keys": [ ... ] } with the same fields as key above — never the token itself. token_prefix (the first 8 characters) and last_used_at help you tell keys apart. The list contains the calling user’s own keys, including revoked ones (their revoked_at is set). Requires settings.api_keys.view_own.
Revoke a key
Section titled “Revoke a key”curl -X DELETE -H "Authorization: Bearer <token>" \ "https://api.pitch2sale.com/api/v1/settings/api-keys/{id}"Returns { "message": "API key revoked" }. Requests with that key fail with 401 from then on. Requires settings.api_keys.delete and, like creating a key, a session JWT.
Rotate a key
Section titled “Rotate a key”Scopes
Section titled “Scopes”A key carries a list of scopes. If you omit scopes or pass an empty array when creating it, the key gets the defaults below that your role permissions back; if your role backs none of them, the request fails with 400 {"error":"Your permissions do not back any API scope"}. The defaults:
| Resource | Scopes |
|---|---|
| Leads | read:leads, write:leads |
| Contacts | read:contacts, write:contacts |
| Opportunities | read:opportunities, write:opportunities |
| Invoices | read:invoices, write:invoices |
| Proposals | read:proposals, write:proposals |
| Projects | read:projects, write:projects |
Two scopes are opt-in and never granted by default:
mcp:read— connect an MCP client and use the read-only tools (MCP server).mcp:write— also use the MCP write tools. A key withmcp:writecan use the read tools too.
A key with a non-default scope list holds only the scopes you pass, so a key for MCP that should also call the REST API needs both, for example ["mcp:read", "read:leads"]. Scope strings are checked against the list above: an unknown or misspelt scope returns 400.
You can only request scopes your role backs. read:<resource> needs a view permission on that resource (own, team or all), write:<resource> needs its create or edit permission, mcp:read needs a leads view permission, and mcp:write needs a leads view permission plus leads create or edit. System administrators hold every scope.