ACTEX Docs - Getting Started

Guided tutorial

Getting started

Agents buy things. Checkouts get stuck. Exceptions fire. And someone asks you "what happened?" — This tutorial walks you through the full ACTEX flow so recovery, resolution, and clean records happen automatically.

Short on time? The 5-minute quickstart covers the same flow with less explanation.

Step 1. Configure environment ~2 min

Point your shell at the hosted sandbox and set your operator token. The operator token authenticates server-to-server actions — think of it as an API key for your platform.

export ACTEX_BASE_URL=https://api.sandbox.actex.ai
export OPERATOR_TOKEN=sandbox-quickstart-token

Verify the connection with a single call:

curl -s -X POST "$ACTEX_BASE_URL/v1/contracts" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"ACTEX:TEMPLATE:DELEGATED_CHECKOUT:V1"}'

If you see a JSON response with a contract_id, you are connected. Save that ID — you will use it in Step 3.

Using a local server instead?

Start ACTEX locally and pass the same token value as an env var:

export ACTEX_BASE_URL=http://127.0.0.1:8080
export OPERATOR_TOKEN=my-dev-token

Set OPERATOR_TOKEN on the server side too so both sides share the same value.

How does operator auth work?

ACTEX has two auth layers. The operator token (this guide) is a shared secret for platform-level actions: creating contracts, managing agents, exporting casefiles. Later, individual agents authenticate with Ed25519 key signatures — covered in the API reference.

Step 2. Create a contract ~5 min

You already created a contract in Step 1. A contract defines what the agent is allowed to do. When a checkout gets stuck, ACTEX uses this contract to decide how to recover — automatically, within bounds.

Copy the contract_id from the Step 1 response and save it:

export CONTRACT_ID=actex:contract:YOUR_ID_HERE

Expected response from Step 1

{"contract_id": "actex:contract:...", "status": "OPEN", "template_id": "ACTEX:TEMPLATE:DELEGATED_CHECKOUT:V1", ...}

Step 3. Submit a result and verify ~10 min

The agent completed a checkout. Record what happened so the answer to "was this authorized?" is always one API call away — not buried in logs.

# Submit a result against the contract from Step 2
curl -s -X POST "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/results" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"result_ref":"RESULT:DEMO:001","status":"PASS","reason_code":"ALLOW_POLICY_MATCH"}'

Now confirm that ACTEX resolved the exception and issued a receipt:

# Check verification — did the result pass policy?
curl -s "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/verification" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

# Retrieve the receipt — clean proof of what happened
curl -s "$ACTEX_BASE_URL/v1/contracts/$CONTRACT_ID/receipt" \
  -H "Authorization: Bearer $OPERATOR_TOKEN"

The CONTRACT_ID from Step 2 is all you need for the next step.

Expected verification response

{"report": {"status": "PASS", ...}, "receipt": {"receipt_id": "actex:receipt:...", "verification_status": "PASS"}}

Step 4. Export Casefile ~10 min

No more "can you pull that receipt?" messages. Export the whole flow as a portable Casefile that anyone can check offline — no platform access, no support escalation.

# Uses the CONTRACT_ID from Step 2
curl -s -X POST "$ACTEX_BASE_URL/v1/casefiles/export" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contract_id":"'$CONTRACT_ID'"}'

Expected response

{"docket_id": "actex:docket:...", "export_profile": "AUDIT", "ok": true, ...}

That is it — a clean record that recovered automatically, resolved without escalation, and proves what happened.

Verify in UI Endpoint index