Sources and Keys

A Source is the machine identity for a script, bot, pipeline, scheduled worker, or agent. Every Source belongs to a workspace and scopes the Actions that process can create and read.

Copy credentials once

The raw Source token and webhook secret are returned only when a Source is created or its credential is rotated. Store them immediately in a secret manager; list and detail responses expose only safe prefixes and timestamps.

Create a Source

You can create one from Sources in the dashboard or through the user-scoped API:

curl -X POST https://api.actionbox.cloud/v1/sources \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production deployer",
    "default_priority": "high"
  }'

The response contains the Source record, a raw axb_live_… token, and the raw webhook signing secret. The token belongs to the process represented by this Source. It is not a browser-user credential.

The key is also bound to the manager authority of the owner or admin who issued it. If that person is demoted below admin, leaves the workspace, or deletes their account, ActionBox revokes keys they issued rather than silently transferring that authority. Rotate the Source key from another owner or admin before a planned departure, then update the integration's secret store.

1. Name the process

Choose a stable name such as production deployer, nightly backup, or support triage bot. The dashboard uses this name when showing which machine asked for a decision.

2. Store both secrets

Put the Source token in the worker or CI secret store. If you will use callbacks, store the webhook secret separately with the service that verifies callback signatures. Do not paste either value into Action descriptions or documentation screenshots.

3. Send a first Action

Use the Source token only in the Authorization header:

curl -X POST https://api.actionbox.cloud/v1/actions \
  -H "Authorization: Bearer $ACTIONBOX_SOURCE_KEY" \
  -H "Idempotency-Key: deploy-v2-18-0" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy v2.18 to production?",
    "description": "Staging checks passed. Review the release before changing production.",
    "priority": "high",
    "options": [
      {"id": "approve", "label": "Approve and deploy"},
      {"id": "hold", "label": "Hold"}
    ]
  }'

See Creating Actions for typed interactions, context blocks, expiration, and idempotency behavior.

Rotate a credential

Use a user session to rotate the Source key or callback secret:

POST /v1/sources/{source_id}/keys/rotate
POST /v1/sources/{source_id}/webhook-secret/rotate

The old key is revoked as the replacement is created. The raw replacement is returned once. For a webhook-secret rotation, future deliveries use the new secret while already queued deliveries keep the secret version captured when they were queued.

Revoke a Source

DELETE /v1/sources/{source_id} revokes the Source and all active keys and returns 204. The Source cannot be edited, restored, or rotated afterwards. Open Actions from that Source are cancelled, queued callbacks are stopped, and Watches are paused. Existing Actions, events, and webhook history remain available for audit; create a new Source when the integration needs access again.

Revocation stops the machine boundary without deleting decisions or audit evidence already recorded.

Source management reference

Operation	Auth	Result
`GET /v1/sources`	User session	List active and revoked Sources with safe key metadata
`GET /v1/sources/{id}`	User session	Read one Source and safe key metadata
`PATCH /v1/sources/{id}`	User session	Update the name or default priority while active
`POST /v1/sources`	User session	Create a Source and return raw credentials once
`POST …/keys/rotate`	User session	Replace the Source key
`POST …/webhook-secret/rotate`	User session	Replace the callback signing secret
`DELETE /v1/sources/{id}`	User session	Revoke the Source and preserve its history

Next: Webhooks and callbacks, Heartbeat Watches, or the REST API reference.