API Documentation

Most agents use ANS through the agent MCP tools below — high-level tools the deployed MCP server exposes over POST /mcp with body { "tool": "tool_name", "params": { ... } }. Call ans_authenticate once, then ans_check_permission before each action. Everything beneath that — the trilateral-handshake primitives, the REST surface, and the SDK — is the underlying infrastructure, for building against the low level directly.

The agent-tool reference below is generated directly from the deployed server's tool definitions, so it always matches what the server actually exposes.

Agent MCP Tools

The primary interface most agents use — the tools the deployed ANS MCP server exposes over POST /mcp. ans_authenticate runs the full trilateral handshake for you; you do not call the low-level primitives directly.

Param	Type		Description
service	string	required	Service key (e.g. 'service:github-mcp' or 'mcp:github:list_repos')
tool	string	optional	Optional tool/action name to check against allowed_actions patterns
context	object	optional	Optional context (e.g. { amount: 100, currency: 'USD' })

Param	Type		Description
service_name	string	required	The service to authenticate with (e.g. 'github-mcp')

Param	Type		Description
service_name	string	required	The service name to restore context for
checkpoint_id	string	optional	Optional: specific checkpoint ID to restore. If omitted, returns the most recent checkpoint.

Onboarding & Catalog Tools

Agent-driven service onboarding and catalog access on the user's gateway. Each requires a delegation chain carrying the noted scope.

Param	Type		Description
agent_did	string	required	The calling agent's DID.
issuance_id	string	required	Issuance ID identifying the signing key on Guardian.
agent_private_key_jwk	object	required	Agent's ECDSA P-256 private key in JWK form (d, x, y, kty='EC', crv='P-256').
delegation	object	required	Agent's delegation chain (must include user_did, agent_did, issuance_id, scopes).
service_name	string	required	Display name for the service.
service_description	string	optional
minimum_attestation_level	string	optional
supported_oob_methods	array	optional
max_session_duration_seconds	number	optional
service_callback_url	string	optional

Param	Type		Description
agent_did	string	required
issuance_id	string	required
agent_private_key_jwk	object	required
delegation	object	required
service_did	string	required	DID of the catalog-registered service to add.

Param	Type		Description
agent_did	string	required
issuance_id	string	required
agent_private_key_jwk	object	required
delegation	object	required
service_did	string	required
request_context	object	optional

Param	Type		Description
agent_did	string	required
issuance_id	string	required
agent_private_key_jwk	object	required
delegation	object	required
page	number	optional
limit	number	optional
search	string	optional

Param	Type		Description
agent_did	string	required
issuance_id	string	required
agent_private_key_jwk	object	required
delegation	object	required
service_did	string	required

---

Underlying infrastructure — the primitives below are wrapped by the agent tools above. Use them directly only if you are building against the underlying protocol (e.g. via the SDK).

Gateway API

The Gateway is the service-side trust anchor. It generates challenges, verifies Guardian signatures, and issues receipts.

Base URL: https://agenticnameservice.ai

Handshake primitives — wrapped by ans_authenticate, not called directly by agents

// Response
{
  "gateway_id": "did:uns:gateway:dev-01",
  "registration_status": "active",
  "version": "0.0.1",
  "supported_attestation_levels": ["session_only", ..., "hardware_key"]
}

Param	Type		Description
service_name	string	required	Service slug identifier

Param	Type		Description
service_name	string	required	Service to authenticate for
service_account_id	string	optional	Returning user's hashed account ID
request_context	object	optional	Flat key-value metadata (feature, action, amount, etc.)
dynamic_override	object	optional	Per-request attestation override

// Response
{
  "nonce": "64-char hex",
  "gateway_id": "did:uns:gateway:dev-01",
  "service_name": "my-service",
  "attestation_level_required": "passkey",
  "service_gateway_sig": "hex (5-field canonical)",
  "gateway_sig": "hex (7-field canonical)",
  "issued_at": "ISO 8601",
  "expires_in": 300
}

// Response (success)
{ "receipt_id": "uuid", "status": "authorized" }

// Response (error)
{ "error": { "code": "ANS_SIGNATURE_INVALID", "message": "...", "retryable": false } }

REST Endpoints (19)

Health & Info

Services

Receipts

Rules & Stats

Onboardings & Admin

Guardian API

The Guardian is the user's Identity Guardian — a commercial entity competing on who protects the user's identity best. It verifies challenges, evaluates policy, signs tokens, and manages OOB authentication.

Base URL: https://guardian.agenticnameservice.ai

Signing primitives — internal Guardian tools, wrapped by the agent tools above

Param	Type	Description
nonce	string	From challenge
gateway_id	string	From challenge
service_name	string	From challenge
attestation_level_required	string	From challenge
service_gateway_sig	string	From challenge
gateway_sig	string	From challenge
oob_request_id	string	For polling after OOB approval

// Response (auto-approved)
{ "guardian_sig": "hex", "approval_source": "rule", ... }

// Response (OOB required)
{ "status": "pending_approval", "oob_request_id": "oob_xxx" }

Param	Type	Description
gateway_id	string	Gateway DID
service_name	string	Service slug
gateway_endpoint	string	Gateway URL
manifest	object	Service manifest (optional, avoids Worker-to-Worker fetch)

Param	Type	Description
gateway_id	string	Gateway DID
service_name	string	Service slug

REST Endpoints (48)

Info & Sessions

Authentication

Passkeys (WebAuthn)

TOTP (Authenticator App)

Agents

OOB Approval

Services & Registrations

Devices

Registrations & Enlistments

Account & Verification

Ceremonies & Receipts

QA & Diagnostics

Coordination Node API

The Coordination Node is the DNS-like directory. Single shared instance serving all environments. Stores public keys and endpoints for Gateways and Guardians.

Base URL: https://cn.agenticnameservice.ai

// GET /lookup/did:uns:gateway:dev-01
{
  "node_id": "did:uns:gateway:dev-01",
  "public_key": "04...",
  "endpoint_url": "https://...",
  "node_type": "gateway",
  "status": "active"
}

SDK — underlying infrastructure

Most agents should use the agent MCP tools above. The SDK is the client for developers building directly against the underlying trilateral handshake. Install: npm install @agentic-name-service/sdk · npm

import { AgentClient } from "@agentic-name-service/sdk";

const agent = new AgentClient({
  gatewayUrl: "https://agenticnameservice.ai",
  guardianUrl: "https://guardian.agenticnameservice.ai",
});

// Authenticate — runs the full trilateral handshake against the primitives below
const receipt = await agent.authenticate("my-service", {
  requestContext: { feature: "transfer", amount: 500 },
  onOobRequired: (id, url) => {
    console.log("User must approve at:", url);
  },
});

console.log("Authorized:", receipt.receipt_id);

Error Codes

All errors follow the format: { "error": { "code": "ANS_...", "message": "...", "retryable": bool, "timestamp": "ISO 8601" } }

Code	HTTP	Retryable	Description
ANS_INVALID_REQUEST	400	No	Malformed request
ANS_UNAUTHORIZED	401	No	Missing auth
ANS_SIGNATURE_INVALID	401	No	Sig verification failed
ANS_IDENTITY_INVALID	503	Yes	Node identity self-check failed
ANS_ATTESTATION_LEVEL_MISMATCH	403	Yes	Provided < required
ANS_SERVICE_NOT_REGISTERED	404	No	Service not in Guardian
ANS_SERVICE_BLOCKED	403	No	User blocked service
ANS_NONCE_EXPIRED	410	No	Nonce TTL exceeded (5 min)
ANS_NONCE_REPLAY	409	No	Nonce already consumed
ANS_OOB_FAILED	401	Yes	OOB auth failed
ANS_USER_DECLINED	403	No	User rejected request
ANS_DYNAMIC_OVERRIDE_BELOW_FLOOR	400	No	Override below minimum
ANS_SERVICE_CALLBACK_TIMEOUT	504	Yes	Service callback >10s
ANS_SERVICE_CALLBACK_ERROR	502	Yes	Service callback 5xx
ANS_MANIFEST_SIGNATURE_INVALID	403	No	Manifest signature verification failed
ANS_MANIFEST_CHANGED	409	Yes	Manifest changed during handshake
ANS_RATE_LIMITED	429	Yes	Rate limit exceeded
ANS_NODE_NOT_FOUND	404	No	Node not in CN registry
ANS_ROTATION_IN_PROGRESS	409	Yes	Key rotation already in progress

Full catalog: 28+ error codes. See packages/protocol-types/src/errors.ts.

Attestation Hierarchy

8 levels, weakest to strongest. Stronger satisfies weaker.

Level	Index	Description
session_only	0	No user interaction
email_confirmation	1	Email code
sms_otp	2	SMS code via Twilio Verify
totp	3	Authenticator app (RFC 6238)
device_signature	4	Software keypair signature
passkey	5	WebAuthn/FIDO2 (UP flag set, may use PIN)
biometric	6	WebAuthn with UV=true (Touch ID, Face ID)
hardware_key	7	FIDO2 hardware security key

Note: passkey does NOT satisfy biometric. A passkey assertion with UV=true (User Verified) maps to biometric level. On devices without biometric hardware, passkeys may be approved with only a password.

Integration Guides

Guide	Description
Cloudflare Worker	Add ANS authentication to your Cloudflare Worker in 15 minutes. Auth middleware, receipt verification, attestation-level gating.
LangChain	Use ANS receipts as tool authorization in LangChain. Python and TypeScript examples with custom BaseTool pattern.
Custom Guardian	Build a custom Identity Guardian. 6 MCP tools, D1/KV/R2 infrastructure, key generation, canonical signing, OOB authentication.
First Handshake Tutorial	"Register Your First Service" — zero to a working receipt in under 30 minutes.

Full guides available in the docs/guides/ directory.

OpenAPI Specifications

Machine-readable API definitions in OpenAPI 3.1 format:

Spec	Description
api/gateway/openapi.yaml	Gateway REST API (19 endpoints)
api/gateway/mcp-tools.yaml	Gateway MCP tools (4 tools)
api/guardian/openapi.yaml	Guardian REST API (48 endpoints)
api/guardian/mcp-tools.yaml	Guardian MCP tools (6 tools)
api/coordination-node/openapi.yaml	Coordination Node public API
api/coordination-node/openapi-admin.yaml	Coordination Node admin API
api/shared/schemas.yaml	Shared schema definitions (71 schemas)

Generated MCP tool catalogs (JSON): api/generated/gateway-mcp-tools.json and api/generated/guardian-mcp-tools.json. Regenerate with pnpm generate:mcp.