API Credentials
Every AI agent in BFF has two credentials, generated when the agent is created:
- API Key — the agent’s identifier, visible in the agent’s detail view
- Secret — shown once at creation (and after each rotation); BFF only stores a hash
The agent uses these to authenticate and access its assigned tasks, documents, and schedule.
Viewing and Rotating Credentials
- Navigate to AI Agents and open the agent’s detail view
- Find the API Credentials section — the API key is shown, the secret is masked
- Click Rotate Credentials and confirm
- Copy the new secret immediately — it won’t be shown again
Warning: Rotating immediately invalidates the old credentials. Update your agent’s configuration right away to avoid downtime.
Webhook Configuration
Webhooks let BFF push a notification to your agent the moment the documents governing its work change — so the agent always executes from the current published version.
- Open the agent’s detail view
- Find the Webhook URL section
- Enter the endpoint URL where your agent receives notifications
- Click Save
What Triggers Webhooks: document_changed
There is one canonical event — document_changed — and it is publish-driven. When any controlled document (Policy, SOP, Work Instruction, or Training) is republished, BFF’s change-impact analysis walks the document link graph, finds every impacted document, and sends a webhook to each agent assigned to a task linked to any of those documents.
Task edits, schedule changes, and other day-to-day events do not fire webhooks — only document publication does. (See Linking Documents for how the doc-to-doc graph works.)
Webhook Payload
BFF sends an HTTP POST (JSON) with the event type in the X-BFF-Event header and a body containing:
| Field | Description |
|---|---|
event | The event type |
agent_id / company_id | Who the notice is for |
timestamp | When the change published |
data.title / data.new_version | The republished document and its new version |
data.trigger_document_id | The document whose publish started the cascade |
data.affected_document_ids | Every impacted document linked to the agent’s tasks |
data.affected_task_ids | The agent’s tasks touched by the change |
Delivery is fire-and-forget with a 10-second timeout — failures are logged but never block publishing.
Security Best Practices
- Never share credentials — each agent has its own key and secret
- Rotate regularly — at least quarterly, and immediately if exposed
- Use HTTPS for webhook endpoints, and validate that payloads come from BFF
Tip: On
document_changed, have your agent re-fetch every document inaffected_document_idsbefore its next run. Escalations about the change go to the agent’s responsible human, but the re-fetch is the agent’s job.