Authentication - BeforeQuery

Public API requests authenticate with per-project client keys, created in the dashboard under Project → Integration Credentials or via POST /api/v1/projects/:projectId/client-keys.

Public client key (browser-safe)

Prefix: bq_pk_…
Safe to ship in browsers and mobile apps; scoped to one project.
Optional origin allowlist — requests are only accepted from listed origins; wildcards like https://*.example.com are supported.
Optional reCAPTCHA v3 enforcement (require_captcha) for abuse protection.

curl https://api.agents.beforequery.com/api/v1/public/projects/proj_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/projects/proj_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

If the public key has require_captcha enabled, send a reCAPTCHA v3 token:

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.

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 project is rejected with 403.

Managing keys

Dashboard (JWT) endpoints:

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

​Public client key (browser-safe)

​Client ID + secret (server-side)

​Header summary

​CAPTCHA

​Group permissions

​Managing keys