Reference
Keys
How site keys work, why Form Capture keys are secret while Engage keys are publishable, and how to rotate safely.
Two kinds of key
All apps use keys that look the same — bk_live_ followed by a random secret — sent in the same header. They differ in where they are allowed to live.
| Form Capture | Engage SDK (AI Chat · Managed Forms · Support Desk) | |
|---|---|---|
| Sent from | Your server | The browser (and servers) |
| Exposure | Secret — never in client code | Publishable — sits in your HTML |
| Boundary | Possession of the key | Per-site origin lock + rate limits |
| If leaked | Revoke the exposed key and deploy a replacement | Revoke an exposed key; browser origin checks do not make a key harmless |
| Env var name | BUCKHY_CAPTURE_KEY (server only) |
NEXT_PUBLIC_BUCKHY_ENGAGE_KEY or similar |
Never put a Form Capture key in NEXT_PUBLIC_*, VITE_* or any bundle a browser downloads.
Sending the key
X-Api-Key: bk_live_…
X-Service-Key is accepted as an alias for server integrations. Credentials are bound to their website, environment and app family. The bk_live_ prefix alone does not identify the environment. A staged replacement can overlap its previous credential; values are still shown only once.
Rotation and revocation
Open API > Credentials. Credential issuance, replacement, retirement and revocation require identity verification within the last ten minutes. For a planned deployment, use staged replacement so the previous credential remains valid while you install the new one.
- Choose Prepare replacement, then Create replacement, and store its one-time value securely. The default expiry is 90 days; the portal also offers 30 or 365 days.
- Deploy the replacement to your server or the Engage build environment.
- Verify successful traffic with the replacement in the correct website and environment.
- Explicitly retire the previous credential only after verification. Confirm the replacement is deployed and tested, then choose Retire old key.
Emergency rotation or revocation is different: it immediately denies the old key and may interrupt deployments still using it. Do not use that path as a substitute for a staged deployment.
If the issuing response was lost, retrying does not reveal the secret again or silently mint another key. Inspect the saved credential state and deliberately replace or abandon the staged credential if its value was not retained. Provider and deployment behaviour must still be verified; staging alone is not a zero-downtime guarantee.
Requests with a revoked key return 401 invalid or revoked developer key (Form Capture) or 401 invalid or revoked engage key (Engage).
Storage on Buckhy's side
- Keys are stored as SHA-256 hashes. The plaintext exists only in the response that issued it.
- Lookups are by hash, so Buckhy cannot recover or re-display a key.
- Revoked keys are kept as revoked records for audit; they can never authenticate again.