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 minted before the user verified — is rejected at request time with requires_email_verification: true.
You must be a tenant admin. Non-admin members can view existing keys but cannot create, edit, or revoke them.

If you don’t have these prerequisites, the dashboard surfaces a verification banner or hides the Create API Key button accordingly.

Steps

Go to the REST API page in the Pathbound dashboard.
Click Create API Key and assign the scopes you need.
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, 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"
  }
}

For legacy keys created before scopes existed, scopes shows the expanded grant the key actually exercises (all non-opt-in scopes) rather than an empty array.

Scopes

API keys can be scoped to limit what they are allowed to do. If a key has no scopes, it receives access to all non-opt-in scopes for backward compatibility (legacy keys) — opt-in scopes like actions:write must always be granted explicitly.

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.
`actions:write`	Opt-in. Real-world side effects on the tenant’s behalf — sending email via Gmail/Resend, managing Resend segments and broadcasts.

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"
}

Using your key with MCP

The same API keys work on the MCP server (https://mcp.pathbound.ai/mcp) as static bearer tokens — 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": "Unauthorized",
  "timestamp": "2026-04-29T12:34:56.000Z"
}

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

Have the issuing user click the magic link in their welcome email, then retry — no need to mint a new key.