DOCS
Dashboardnorth_eastGet an API keyvpn_key
PAI Chat·Authentication

Authenticating your PAI Chat requests

PAI Chat uses API keys for programmatic access. Send the key in the x-api-key header when calling protected PAI Chat API routes.

lock
API-key failures are explicit. Invalid, disabled, expired, or missing keys return 401. Scope mismatches return 403. Rate-limited keys return 429.

Key scoping: organization vs. chatbot

Every key is locked to a scope at creation time and cannot be escalated later.

ScopeWorks forCreated from
Organization keyAny chatbot in the organizationDashboard → Settings → API keys
Chatbot keyOne chatbot onlyChatbot → API & Usage tab

Requests that target a specific chatbot must include x-chatbot-id. Requests against organization-level routes must include x-organization-id, and it must match the organization the key was created for — a mismatch returns 403 Forbidden, even for a chatbot key whose organization matches but chatbot doesn't.

Creating an API key

Sign in to the PAI Chat frontend:

  • Organization key — open Settings → API keys and create a key. It authenticates for any chatbot in the organization. Requires organization admin permission.
  • Chatbot key — open the chatbot's API & Usage tab and create a key. It authenticates for that chatbot only. Requires chatbot admin permission.

The full key is displayed only once, so store it in a secrets manager or environment variable before leaving the page.

HTTP
x-api-key: YOUR_CHAT_API_KEY

Always send x-chatbot-id explicitly rather than relying on request origin to resolve it — implicit resolution exists for browser widget embeds, not for server-to-server calls.

curl https://chat-api-dev.paicloud.ai//auth/get \
  -H "x-api-key: $PAI_CHAT_API_KEY" \
  -H "x-chatbot-id: YOUR_CHATBOT_ID"

Managing keys

Use the PAI Chat frontend for everyday key creation, rotation, and deletion.

ActionEndpointNotes
Create organization keyPOST /api-keys/createRequires x-organization-id + org admin
Create chatbot keyPOST /api-keys/chatbot/createRequires x-chatbot-id + chatbot admin
List keysGET /api-keys/listKeys owned by the authenticated user
Inspect keyGET /api-keys/get?id=
Update keyPOST /api-keys/updateEnable/disable, rename, adjust limits
Delete keyPOST /api-keys/delete

Optional fields on create/update: expiresIn (seconds), remaining (request budget), refillAmount/refillInterval (ms), rateLimitEnabled, rateLimitTimeWindow (ms), rateLimitMax, and permissions.

Authentication failures

StatusMeaning
401Key is missing, invalid, disabled, or expired
403Key's organization or chatbot scope does not match the request
429Key exceeded its rate-limit window

Limits and rotation

The default API key rate limit is 1000 requests per day per key. Rotate keys by creating a replacement, updating the consuming service, and then deleting the old key.

Rotation flow
# 1. Create a replacement key (Settings → API keys, or a chatbot's API & Usage tab)
# 2. Deploy the new key to the consuming service
# 3. Confirm traffic succeeds with the new key
# 4. Delete the old key
shield
Treat API keys like passwords. Never embed a PAI Chat API key in browser-side application code, source control, logs, issue trackers, or screenshots.