Authentication

Authenticate API requests using API keys.

API Key Types

Name	Type	Description
`Server key`	bnc_sv_*	Full access. Use from your backend servers only. Can resolve conversations and manage all data.
`Client key`	bnc_cl_*	Limited access. Safe for mobile apps and browser clients. Restricted by allowed origins and bundle IDs.

Creating API Keys

Create API keys from your Bancroft dashboard under Settings → Integrations → API Keys, or via the management API:

bash

curl -X POST https://your-domain.com/api/integrations/api-keys/create/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=..." \
  -d '{
    "name": "My iOS App",
    "key_type": "client",
    "allowed_bundle_ids": ["com.mydomain.app"]
  }'

The plaintext key is returned only once in the response. Store it securely.

Using API Keys

Include your API key in every request using one of these methods:

Option 1: X-API-Key header (recommended)

bash

curl https://your-domain.com/api/v1/conversations/ \
  -H "X-API-Key: bnc_sv_a1b2c3d4e5f6..."

Option 2: Authorization Bearer header

bash

curl https://your-domain.com/api/v1/conversations/ \
  -H "Authorization: Bearer bnc_sv_a1b2c3d4e5f6..."

Client Key Security

Client keys can be restricted by allowed origins (for web) and bundle IDs (for mobile). When these are set, requests from other origins or bundles are rejected.

json

{
  "name": "My Web Widget",
  "key_type": "client",
  "allowed_origins": ["https://app.mydomain.com", "https://www.mydomain.com"]
}

Error Responses

json

{
  "detail": "Invalid or revoked API key."
}

Status 401 is returned for missing, invalid, or revoked keys.

Loading…