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.io/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

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.

Scope	Grants
agents:read	List and retrieve agents and agent runs.
agents:write	Create, update, and delete agents.
agents:trigger	Trigger manual agent runs.
agents:approve	Approve or reject pending agent actions.

Endpoints that require a specific scope will return 403 Forbidden if the key does not have it.

Authentication Errors

Status	Meaning
401	Missing or invalid API key.
403	Key is valid but lacks the required scope.

Example 401 response:

{
  "status": "error",
  "error": "Unauthorized",
  "timestamp": "2025-01-01T00:00:00.000Z"
}

Verify Your Key

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

GET /v1/auth/status

A successful response returns your user and tenant information.