Authentication

Every request to the Pathbound API (except the health-check and public form-submission endpoints) must include a valid API key.

Obtaining an API Key

Prerequisites

Before you can create an API key:

Your email must be verified. Keys can be created only by verified users. A key whose issuing user is unverified, including a key created before the user verified, is rejected at request time with requires_email_verification: true.
You must be a workspace admin. Other members can view existing keys but cannot create, edit, or revoke them.

If you don’t have these prerequisites, the dashboard shows a verification banner or hides the button that creates a key.

Steps

Open Settings → API keys in the Pathbound dashboard.
Create a key, name it, and tick the scopes it needs. A new key starts with the four read scopes for contacts, companies, deals and events ticked.
Copy the key. It is shown only once.

A workspace can hold several keys. Give each integration its own key with only the scopes it needs, so that you can revoke one without touching the others.

A key acts as the user who created it. That matters for the endpoints that act from a person’s own account: an email sent with the key through Gmail goes out from a mailbox that user connected. If that user leaves the workspace, their keys stop working.

Using the API Key

Pass the key in the Authorization header with the Bearer scheme:

curl https://api.pathbound.ai/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

Verify Your Key

Use the auth status endpoint to confirm your key is working:

curl https://api.pathbound.ai/v1/auth/status \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response returns your user and tenant information, plus the key’s effective scopes:

{
  "status": "success",
  "authenticated": true,
  "auth_type": "api_key",
  "key_id": "1a2b3c4d",
  "scopes": ["contacts:read", "events:read"],
  "user": {
    "user_id": "abc123",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "tenant_id": "tenant_xyz"
  },
  "workspace": {
    "id": "tenant_xyz",
    "name": "Acme Corp",
    "ws": "acmecorp"
  }
}

workspace is the workspace the key reaches. ws is the value an MCP connector URL names it by, and name is null when the workspace’s name holds characters the MCP server does not show to a model.

For a key created before scopes existed, scopes shows what the key can actually do (every scope that is not opt-in) rather than an empty array.

Scopes

A key can do only what its scopes allow. Every endpoint’s page names the scope it needs.

Scope	Grants
`contacts:read`	List, search, and retrieve contacts, their conversations, meetings and notes.
`contacts:write`	Create, update, delete and tag contacts, and write contact notes. Create segments of contacts.
`companies:read`	List and retrieve companies and their notes.
`companies:write`	Create, update, delete and tag companies, and write company notes. Create segments of companies.
`deals:read`	List and retrieve deals and their notes.
`deals:write`	Create, update, delete and tag deals, and write deal notes.
`events:read`	List and aggregate tracked events, read a contact’s timeline, and list forms.
`knowledge:read`	List, search and read the workspace’s knowledge pages.
`streams:read`	Read streams and automations: their triggers, state and delivery log. Never where an HTTPS stream delivers.
`knowledge:write`	Opt-in. Create knowledge pages and edit unlocked ones. What a key writes is shown as unverified.
`streams:write`	Opt-in. Create, change and delete automations, which keep acting by themselves after the call that made them.
`actions:write`	Opt-in. Real-world side effects on your workspace’s behalf: sending email through Gmail (now or scheduled, and drafts held by Pathbound), acting in your Resend account (segments, emails, events, broadcasts), Apollo sequences and single emails, and Instantly leads. It also gates the reads that describe what you can send from: Gmail mailboxes and the outbox, Apollo mailboxes, sequences, schedules and per-contact engagement.
`enrichment:write`	Opt-in. Enrichment and prospecting, which spend your credits with Apollo or Hunter.

Endpoints that require a specific scope return 403 Forbidden if the key does not have it. Most endpoints declare a single required scope. A few need two (reading a company’s conversations needs companies:read and contacts:read), and a few need a scope that depends on what you ask for (POST /v1/aggregate needs the read scope of the entity you aggregate).

Opt-in scopes

Four scopes are marked opt-in because they do more than read and write your own records: they send to real people, spend money, or leave a standing instruction behind. A key has one of them only if you ticked it when you created the key. Ticking “grant all permissions” ticks them too.

Keys without scopes

A key created before scopes existed has none. It keeps working, with every scope that is not opt-in. It never has an opt-in scope: to use one, create a new key. GET /v1/auth/status shows such a key’s effective scopes.

Scope error response

{
  "status": "error",
  "error": "Insufficient API key scopes. Missing: events:read",
  "required_scopes": ["events:read"],
  "timestamp": "2026-10-12T12:34:56.000Z"
}

Using your key with MCP

The same API keys work on the MCP server (https://mcp.pathbound.ai/mcp) as static bearer tokens. That is the way to connect headless MCP clients that can’t complete a browser login. Interactive clients like Claude.ai instead use Pathbound’s native OAuth login and need no key. See MCP Authentication for both flows.

Authentication Errors

Status	Meaning
`401`	Missing or invalid API key.
`403`	Key is valid but lacks the required scope.
`429`	Rate limit exceeded.

Example 401 response:

{
  "status": "error",
  "error": "Invalid Bearer token!",
  "timestamp": "2026-10-12T12:34:56.000Z"
}

The error text says what was wrong: the Authorization header is missing, it is not a Bearer token, the token is not a key of any workspace, or the key has been deactivated.

Unverified-issuer 401

If the user who minted the key is not (or is no longer) email-verified, every request authenticated by the key is rejected:

{
  "status": "error",
  "error": "Email verification required",
  "requires_email_verification": true,
  "timestamp": "2026-10-12T12:34:56.000Z"
}

Have the user who created the key click the link in their welcome email, then retry. The key does not need to be replaced.