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

1. Go to the API Keys page in the Pathbound dashboard.
2. Click Create API Key and assign the scopes you need.
3. Copy the key — it is only shown once.

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:

{
  "status": "success",
  "authenticated": true,
  "user": {
    "user_id": "abc123",
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "tenant_id": "tenant_xyz"
  }
}

Scopes

API keys can be scoped to limit what they are allowed to do. If a key has no scopes, it receives unrestricted access for backward compatibility (legacy keys).

Scope	Grants
contacts:read	List, search, and retrieve contacts and their events.
contacts:write	Create, update, delete contacts and contact notes.
companies:read	List and retrieve companies.
companies:write	Create, update, delete companies and company notes.
events:read	List and aggregate tracked events.
segments:read	List segments and retrieve segment members.
segments:write	Reserved for future segment write endpoints.
actions:read	List and retrieve actions.
actions:write	Create, update, approve, reject, execute, cancel actions.
agents:read	List and retrieve agents and agent runs.
agents:write	Create, update, delete agents.
agents:trigger	Trigger manual agent runs.
agents:approve	Approve or reject pending agent actions.
identities:read	List and retrieve sender identities.
identities:write	Create, update, delete identities; manage LinkedIn auth.

Endpoints that require a specific scope return 403 Forbidden if the key does not have it. Most endpoints declare a single required scope; some (like POST /v1/aggregate) require a scope that depends on which entity you are querying.

Scope error response

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

OAuth (MCP only)

If you connect Pathbound to Claude.ai or another MCP client, the MCP server issues a short-lived JWT via Pathbound’s native login flow. You do not need an API key for MCP — see MCP Authentication.

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": "Unauthorized",
  "timestamp": "2026-04-29T12:34:56.000Z"
}