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.

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 leaves Actions, events, and webhook history queryable but stops the Source and its keys from creating new Actions. Create a new Source if a revoked Source must return; revoked Sources cannot be restored or rotated.