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

In the app: Settings → API keys → create. Your role needs the settings.api_keys.create permission.

With the API (authenticated as the user who will own the key):

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. 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

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

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.

Rotate a key

There is no rotate endpoint

To rotate a key: create a new key with a new label, switch your integration to it, confirm it works (its last_used_at updates), then revoke the old key. Both keys work during the switch, so there is no downtime.

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:

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 with mcp:write can 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 not checked against a list: a misspelt scope is stored as-is and grants nothing.

Where scopes are enforced today

Scopes are checked on the leads, contacts, opportunities, proposals and invoices endpoints that carry a scope check, and on the MCP endpoint. Other endpoints accept any valid key and rely on the user’s role permissions alone. Give each integration its own user with a role that allows only what it needs.