Testing with Sandbox Keys

Each Source can have one active live key (axb_live_…) and one active test key (axb_test_…). A test key is an environment boundary, not a second permission level: requests made with it create environment: "test" Actions and cannot read or mutate live Actions.

Issue a test key

Test-key management is user-scoped. Rotate or issue it from a signed-in dashboard session:

curl -fsS -X POST \
  "https://api.actionbox.cloud/v1/sources/$SOURCE_ID/keys/test/rotate" \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

The raw replacement token is returned once. Store it in a test-only secret slot; rotating again revokes the previous test key. The live key has a separate rotation route: POST /v1/sources/{source_id}/keys/rotate.

Create and inspect a test Action

Use the test key only on the machine-side API call:

curl -fsS -X POST https://api.actionbox.cloud/v1/actions \
  -H "Authorization: Bearer $ACTIONBOX_TEST_KEY" \
  -H "Idempotency-Key: sandbox-$RUN_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sandbox approval check",
    "interaction": {
      "type": "boolean",
      "label": "Continue the test?"
    }
  }'

The response identifies the test environment. A test process can reconcile it with the Source-scoped route:

curl -fsS "https://api.actionbox.cloud/v1/source/actions/$ACTION_ID" \
  -H "Authorization: Bearer $ACTIONBOX_TEST_KEY"

For a human session, test Actions are hidden from the default live inbox. Ask for the environment explicitly:

curl -fsS \
  "https://api.actionbox.cloud/v1/me/actions?status=all&environment=test" \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN"

What is isolated

Test Actions use the same typed interaction, version/fingerprint binding, expiration, idempotency, and decision rules as live Actions. That makes the sandbox useful for protocol and integration checks without creating a real review notification or consuming live quota.

A compact sandbox checklist

1. Issue a test key through a user session and store it in a test-only secret slot.
2. Create an Action with a stable test idempotency key.
3. Resolve it with the test credential or inspect it with an explicit test inbox filter.
4. Exercise a stale action_version/fingerprint and confirm the client stops on ACTION_CHANGED.
5. Rotate the test key and confirm the old value is rejected with SOURCE_REVOKED.
6. Let test data expire according to the sandbox retention window; do not copy test credentials or receipts into production fixtures.

Next: Sources and keys, Idempotency and dedupe, Errors and safe retries, or Webhooks and callbacks.