Authentication - BeforeQuery

Public API requests authenticate with per-knowledge-base client keys, created in the dashboard under Knowledge Base → Integration Credentials or via POST /api/v1/knowledge-bases/:knowledgeBaseId/client-keys.

Public client key (browser-safe)

Prefix: bq_pk_…
Safe to ship in browsers and mobile apps; scoped to one knowledge base.
Optional origin allowlist — requests are only accepted from listed origins; wildcards like https://*.example.com are supported.
reCAPTCHA v3 enforcement — always required for public keys when reCAPTCHA is configured on the server.

curl https://api.agents.beforequery.com/api/v1/public/knowledge-bases/kb_xxx/search \
  -H "X-Client-Key: bq_pk_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "rate limits"}'

Client ID + secret (server-side)

Prefixes: bq_ci_… (ID) and bq_cs_… (secret).
For backend integrations only — never expose in client-side code.
The secret is hashed at rest and shown exactly once on creation.

curl https://api.agents.beforequery.com/api/v1/public/knowledge-bases/kb_xxx/search \
  -H "X-Client-Id: bq_ci_..." \
  -H "X-Client-Secret: bq_cs_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "rate limits"}'

Header summary

Credential	Header(s)
Public key	`X-Client-Key: bq_pk_…`
Secret pair	`X-Client-Id: bq_ci_…` + `X-Client-Secret: bq_cs_…`
WebSocket	Query params: `?client_key=` or `?client_id=&client_secret=`
MCP / A2A	`X-Client-Key`, `Authorization: Bearer bq_pk_…`, or `?client_key=`

CAPTCHA

Public-key requests must send a reCAPTCHA v3 token whenever reCAPTCHA is configured on the server (check captcha_required in widget-config). Secret pairs are exempt:

HTTP: X-Captcha-Token: <token> header
WebSocket: captcha_token field on the chat frame

The site key to render the challenge comes from the widget-config endpoint. Missing/invalid tokens produce captcha_required / captcha_failed errors.

Rate limits

Client keys can carry an optional rate_limit_per_min (set at creation). 0 or unset applies the deployment default of 600/min; a negative value means unlimited. Requests over the limit receive 429 with X-RateLimit-Limit / X-RateLimit-Remaining headers; on WebSocket, an {"type":"error","code":"rate_limited"} frame.

Group permissions

Client keys can carry allowed_groups: [uuid] restricting retrieval to specific source groups. Any request group_ids are intersected with this set — a request referencing a group outside the key’s allowed set or outside the knowledge base is rejected with 403.

Managing keys

Dashboard (JWT) endpoints:

POST   /api/v1/knowledge-bases/:knowledgeBaseId/client-keys
  {"name": "docs-site", "key_type": "public" | "secret", "allowed_origins": ["https://docs.example.com"]}
GET    /api/v1/knowledge-bases/:knowledgeBaseId/client-keys
DELETE /api/v1/client-keys/:id     # revoke immediately

​Public client key (browser-safe)

​Client ID + secret (server-side)

​Header summary

​CAPTCHA

​Rate limits

​Group permissions

​Managing keys