Every custom integration is authenticated with a single token used as the HMAC signing key in both directions. This guide covers when and how to rotate it.
.env; a token appeared in a screenshot; an ex-employee with access leaves.Rotation produces a new token and keeps the previous token valid for 24 hours. This window lets you:
BONDI_INTEGRATION_TOKEN in your secrets manager.Without this grace window, every rotation would cause downtime equal to your redeploy time (often minutes).
T+0s Rotate clicked in Studio → new token issued, previous token marked with 24h expiry
T+0s Studio shows new token ONCE — copy it now, it cannot be retrieved later
T+0s Bondi (sender) starts signing outbound action calls with the NEW token
T+0s Bondi (receiver) accepts trigger emits signed with EITHER token
T+24h Previous token expires; only the new one works
emit() calls): keep using the old token until you redeploy. Bondi receiver accepts both.BondiGuard only knows about the OLD token until you redeploy.⚠️ There's a window where action calls FROM Bondi can fail until your service has the new token. Plan rotations during low-traffic periods or when you can immediately redeploy.
curl -X POST \
-H "Authorization: Bearer ${YOUR_JWT}" \
https://automation.heybondi.com/v1/workspaces/${WORKSPACE_ID}/integrations/custom-definitions/${SLUG}/rotate-token
Response includes:
{
"slug": "my-crm",
"token": "bnd_tok_...",
"tokenWarning": "Save this token now — it cannot be retrieved again. Update BONDI_INTEGRATION_TOKEN in your environment. The previous token remains valid for 24 hours.",
"previousTokenValidUntil": "2026-04-27T12:34:56.000Z"
}
BONDI_INTEGRATION_TOKEN set:
If you don't redeploy within 24h, the old token expires and you'll see:
BondiGuard rejects (your service uses old token).Recovery: rotate again. You'll get a new token and another 24h window. This is annoying but not catastrophic.
Q: Can I rotate without grace? Currently no — the 24h grace is built in. If you need immediate revocation (e.g. confirmed compromise), contact support to wipe the previous credential immediately.
Q: Do my workflows need to be re-tested after rotation? No. The integration definition (services, actions, triggers, schemas) is unchanged. Only the HMAC key changes.
Q: Does rotation invalidate connection state in Bondi?
No. The integration_connections row is updated in place; existing workflow node bindings still resolve to the same connection.
Q: How do I rotate in a multi-environment setup (dev, staging, prod)? Each environment uses its own integration with its own token. Rotate per-environment as needed.