Sources and Keys

Create a scoped machine identity, use live and test keys safely, and rotate credentials without losing history.

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 is for the process represented by this Source—not for a browser user.

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.

Live and test keys

Each Source can have one active key in each mode:

Mode	Prefix	Use	Dashboard behavior
Live	`axb_live_…`	Real workflow requests	Included in the default live inbox and normal usage
Test	`axb_test_…`	Safe integration checks	Isolated from live Actions, default inbox results, billing usage, push hints, and callbacks

Test Actions are visible when a user explicitly requests environment=test. They are isolated from live inboxes and usage, and do not publish normal push or callback side effects in the hosted service.

One Source, one boundary

A test key cannot read or mutate a live Action, replay a live idempotency result, or cross into another Source or workspace. Keep test and live credentials in separate runtime configurations.

Rotate a credential

Use a user session to rotate the live key, test key, or callback secret:

POST /v1/sources/{source_id}/keys/rotate
POST /v1/sources/{source_id}/keys/test/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. Existing Actions, events, and webhook history remain available for audit; create a new Source when the integration needs access again.

Revoking a Source also pauses its associated Watches. This stops the machine boundary without deleting the decisions it already created.

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 live key
`POST …/keys/test/rotate`	User session	Replace the test 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.

Sources and Keys

On this page