Security

ActionBox separates the identity that creates an Action from the identity that reviews it. Use the smallest credential scope for each job, keep secrets out of Action content, and treat every callback and heartbeat URL as sensitive.

Credential classes

Source and user tokens are stored as hashes. Webhook secrets must remain recoverable for callback signing, so ActionBox encrypts them and reveals the raw value only when the Source is created or its secret is rotated. Watch URLs are bearer capabilities and are intentionally not shown again after creation or rotation.

Protect the callback boundary

ActionBox signs terminal callbacks with the Source webhook secret. Verify X-Actionbox-Signature against the exact raw request bytes and the X-Actionbox-Timestamp before parsing JSON. Use a constant-time comparison, reject stale timestamps, and deduplicate the stable event id. See Webhooks and callbacks for the receiver implementation.

Hosted callback destinations must be public HTTPS endpoints. Do not put credentials in the URL; redirects are not followed. Keep callback secrets out of source control, browser code, issue reports, and request logs.

Resolved Actions can include an immutable Ed25519-signed decision receipt. When the receipt field is present, verify it with the public keys from /.well-known/actionbox-receipt-keys.json when you need independent proof of the decision. Older terminal records may not have a receipt. The receipt key and the callback HMAC secret serve different purposes; neither replaces the other.

Keep Action content safe

Action context is bounded, inert display data. Do not send passwords, API keys, session tokens, Watch URLs, full customer records, private transcripts, or unbounded logs in a title, description, context block, metadata, or response. Instead, include a short summary and an access-controlled link with an appropriate retention policy. A human decision is an authorization record, not proof that the downstream operation succeeded; report the execution outcome separately.

Workspace access

Team workspaces use four roles:

• Owner and admin manage Sources, Watches, members, and workspace settings. They can also review and decide Actions.
• Approver can claim and decide Actions but cannot manage Sources or Watches.
• Viewer has read-only access.

Keep machine credentials on the Source that owns the workload. Use a user session for dashboard and workspace-management calls; a Source key is not a substitute for a user session.

Protect your sign-in

Two-factor authentication is optional for an individual account. In Settings → Account security, select Manage security to set up an authenticator app. Save the recovery codes when they appear; each code works once. After the authenticator is active, you can add a passkey as another way to complete the second-factor check. Your usual ActionBox sign-in remains the first step.

Keep recovery codes outside ActionBox and away from the device you normally use to sign in. If you lose access to your authenticator, use a recovery code on the sign-in screen. Source API keys are separate from this account sign-in setting. If your workspace requires two-factor authentication, complete setup when prompted before reviewing its Actions.

Rotation checklist

1. Create the replacement credential or rotate it from the Source/Watch owner account.
2. Store the one-time value in your secret manager and update the worker or receiver without printing it.
3. Send one controlled request through the replacement path and confirm the resulting resource ID, status, and X-Request-ID.
4. Revoke or archive the old capability and check that old requests fail.
5. Search logs, CI output, browser history, and issue attachments for the old value and remove any copies.

Use DELETE /v1/sources/{source_id} to revoke a Source when the integration is no longer trusted. Revocation cancels its open Actions, stops queued callbacks, and pauses its Watches. Actions, events, and webhook history remain queryable as audit evidence. Create a new Source if a revoked Source must return; revoked Sources cannot be restored or rotated.