Authentication

Peachdesk has three credential families. They are not interchangeable, and sending the wrong one is the most common source of a 401.

Credential	Header	Looks like	Use it for
API key	`X-API-Key`	`bibha_…`	The whole programmatic API — agents, calls, campaigns, telephony configs, analytics, BRAHMA/VAANI/LIPI, Voice Engine
User session token	`Authorization: Bearer …`	a JWT	The dashboard, and the session-only routes below, which no API key can reach
MPS service key	`Authorization: Bearer …`	`pk_live_…` / `pk_test_…`	`/api/v1/mps/*` only — a separate credential issued by a Peachdesk super-admin

If you are writing code against Peachdesk, you almost certainly want an API key in the X-API-Key header. The other two are for the browser session and for the managed model-proxy tier respectively.

API key authentication

API keys are the credential for programmatic requests. Pass your key in the X-API-Key request header.

curl https://api.peachdeskai.com/api/v1/workflow/fetch \
  -H "X-API-Key: bibha_your_api_key"

Keys are prefixed bibha_. A key is scoped to an organization: every resource created or read with it belongs to that organization, and the key carries the permissions of the member who created it.

Create an API key

Create keys in the dashboard under Settings → API Keys, or programmatically with POST /user/api-keys. The full key is returned only once, at creation — store it immediately in a secrets manager or environment variable.

For self-hosted deployments using local auth, sign up and log in via the dashboard first, then create an API key there before making API calls.

Manage API keys

Action	Method	Path
List keys	`GET`	`/user/api-keys`
Create key	`POST`	`/user/api-keys`
Archive key	`DELETE`	`/user/api-keys/{api_key_id}`
Reactivate key	`PUT`	`/user/api-keys/{api_key_id}/reactivate`

Archiving a key immediately revokes it. All subsequent requests using that key return 401.

Session-only routes

Some routes require an interactive user session and refuse an API key outright. An API key is a long-lived organization credential that any member of the organization can mint, and it carries no membership re-check — so the operator surfaces that read cost data, move money, or hand out permissions are not reachable with one. These prefixes are session-only:

Prefix	What lives there
`/api/v1/admin/*`	Operator administration
`/api/v1/sa/*`	Super-admin console
`/api/v1/superuser/*`	Superuser utilities

Sending X-API-Key to any of them returns 401 before the key is even looked up:

{
  "detail": "User session required"
}

Authenticate these routes with the user session token instead:

curl https://api.peachdeskai.com/api/v1/sa/... \
  -H "Authorization: Bearer <your_session_token>"

Nothing in this public reference — agents, calls, campaigns, telephony configurations, analytics, BRAHMA, VAANI, LIPI, or the Voice Engine — is session-only. An API key reaches all of it.

MPS service keys are a different credential

The managed model-proxy routes under /api/v1/mps/* do not accept an API key. They take a service key, issued by a Peachdesk super-admin, sent as a bearer token:

curl https://api.peachdeskai.com/api/v1/mps/llm/v1/chat/completions \
  -H "Authorization: Bearer pk_live_your_service_key" \
  -H "Content-Type: application/json" \
  -d '{"model": "default", "messages": [{"role": "user", "content": "Hi"}]}'

	API key	MPS service key
Prefix	`bibha_`	`pk_live_` (production), `pk_test_` (sandbox)
Header	`X-API-Key`	`Authorization: Bearer`
Created by	any member, self-serve	Peachdesk super-admin, on request
Reaches	the public API	`/api/v1/mps/*` only

A malformed or missing bearer on an MPS route returns:

{
  "detail": "Missing or malformed Authorization header. Expected: 'Authorization: Bearer pk_live_...'"
}

Service keys also enforce a per-key concurrency limit; exceeding it returns 429.

Header precedence

If a request carries both X-API-Key and Authorization, the API key wins — except on the session-only routes above, where the presence of X-API-Key is itself the rejection. Send exactly one credential.

Error responses

Status	Cause
`401 Unauthorized`	Missing, invalid, expired, or archived credential — or an API key sent to a session-only route
`402 Payment Required`	Authenticated, but the organization is out of credits or has hit its daily spend cap
`403 Forbidden`	Valid credentials, but insufficient permissions or the resource belongs to another organization

{
  "detail": "Invalid or expired API key"
}

Authentication succeeding does not mean the request is free. Requests that run a model draw on your organization’s credit balance and are refused with 402 once it is exhausted — see Errors.

Resources

Authentication & Errors

Voice Engine API

Bibha BRAHMA LLM

Bibha VAANI TTS

Bibha LIPI STT

API key authentication

Create an API key

Manage API keys

Session-only routes

MPS service keys are a different credential

Header precedence

Error responses

​API key authentication

​Create an API key

​Manage API keys

​Session-only routes

​MPS service keys are a different credential

​Header precedence

​Error responses

API key authentication

Create an API key

Manage API keys

Session-only routes

MPS service keys are a different credential

Header precedence

Error responses