Developer guide

This guide is for two kinds of developer:

• Agent builders whose agent calls a protected API route or MCP tool and must get through an approval, a disconnect or a restart without losing work or writing twice.
• Provider developers whose application receives those calls and must commit each authorised operation exactly once and say what it committed.

Everything here describes what the code in this repository does today (contract version 2026-11-14). Where the code and the product brief differ, the page says so.

The contract in one paragraph

An agent authenticates with OAuth 2.1 client_credentials using private_key_jwt and a DPoP proof, and gets a 5-minute access token bound to its key. It submits an action with a stable operation_key and the material fields the provider will commit. Axiom answers with a durable action ID and a state. If a person must approve, the state is pending_approval and nothing has happened at the provider. The agent reads status until the state is approved, then resumes as the same agent with the same parameters. Axiom rechecks authority, claims execution once, dispatches to the provider with a signed Axiom-Authorization header and records the provider's signed outcome in a receipt that anyone can verify offline.

Operation	Endpoint	Page
Discover	GET /v1/capabilities	Waiting for a decision
Token	POST /oauth/token	Authentication
Submit	POST /v1/actions	Submit, status and resume
Status	GET /v1/actions/{id}	Submit, status and resume
Resume	POST /v1/actions/{id}/resume	Submit, status and resume
Cancel	POST /v1/actions/{id}/cancel	Submit, status and resume
Receipt	GET /v1/actions/{id}/receipt	Submit, status and resume
Delegate	POST /v1/grants/{grant_id}/delegate	Explicit delegation
Authorize	POST /v1/authorize (provider)	Embedded SDK
Outcome	POST /v1/actions/{id}/outcome (provider)	Embedded SDK

The same contract is reachable three ways:

Path	Host	Read
REST API	api.sectigoaxiom.com	Submit, status and resume
Hosted Gateway HTTP proxy, /p/{project_id}/http/*	gw.sectigoaxiom.com	Submit, status and resume
Hosted Gateway MCP proxy, /p/{project_id}/mcp, and the Axiom MCP server, /mcp	gw. and mcp.sectigoaxiom.com	MCP

In local development everything runs on http://localhost:8787, with the gateway under /gw (for example http://localhost:8787/gw/p/prj_…/http/v1/invoices/417/refunds) and the Axiom MCP server at /mcp.

Where to start

1. Run the first ten minutes sample in the console. It does every step below in your browser against synthetic data.
2. Read authentication and set up the axiom-headers.ts helper so the curl examples in this guide work as written.
3. Read idempotency and conflicts before you write a retry loop.
4. Pick a waiting strategy that matches your runtime.
5. If you are the provider, read protect my service and then the embedded SDK provider guide.

Status of the developer preview

• The TypeScript SDK (@sectigo/axiom-sdk) and the axiom CLI live in packages/sdk of the repository. They are not yet published to a package registry; use them from the monorepo, where the CLI runs its TypeScript sources through tsx.
• The Python example in examples/python is a single-file reference client, not a supported SDK.
• Customer-hosted gateway packaging and existing-gateway adapters (Kong, Apigee, AWS API Gateway) are not in this repository. The control-plane side (gateway registration, heartbeat and signed policy bundles) is; see fleet, gateways and cutover.

Reference

• API reference, generated from the machine-readable contract.
• Errors and reason codes: every code and reason_code with what to do.
• Receipt and event formats.
• Agent skill for agents that should follow the contract by themselves.