AffixIO API Documentation (v1)

Real routes mounted under /v1 from backend code.

Excluded by request: account edit endpoints are not shown.

Auth

Public: GET /v1/health, GET /v1/openapi.json.

Other endpoints require API key.

Content-Type: application/json
Accept: application/json
X-API-Key: aff_your_key

Quick start

curl -sS https://api.affix-io.com/v1/health

curl -sS -X POST https://api.affix-io.com/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: aff_your_key" \
  -d '{"circuit_id":"agentic-payment-permission","identifier":"agent:abc123","context":{"amount":24.99,"currency":"GBP"}}'

Quantum-safe in 5 minutes

Use hybrid mode by default during migration. This keeps classical verification paths available while adding post-quantum signatures.

1) Install SDK

npm install @affixio/sdk

2) One-command quick run

AFFIX_API_KEY=affix_xxx AFFIX_ORG_ID=org_xxx node --input-type=module -e "import { AffixIO } from '@affixio/sdk'; const sdk = new AffixIO({ apiKey: process.env.AFFIX_API_KEY, orgId: process.env.AFFIX_ORG_ID, baseURL: 'https://api.affix-io.com' }); const out = await sdk.circuits.quantumSafeToken({ dilithiumSignature:'RGlsaXRoaXVtX3NpZ25hdHVyZV9wbGFjZWhvbGRlcl9iYXNlNjR1cmw', tokenExpiry: Math.floor(Date.now()/1000)+3600, decision:1, currentTime: Math.floor(Date.now()/1000) }); console.log(JSON.stringify(out, null, 2));"

3) Generate hybrid token

curl -sS -X POST https://api.affix-io.com/v1/tokens/generate-quantum-safe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: aff_your_key" \
  -d '{
    "subject":"user_123",
    "alg_classical":"Ed25519",
    "alg_pq":"Dilithium2",
    "sig_classical":"Q2xhc3NpY2FsX3NpZ25hdHVyZV9wbGFjZWhvbGRlcl9iYXNlNjR1cmw",
    "sig_pq":"RGlsaXRoaXVtX3NpZ25hdHVyZV9wbGFjZWhvbGRlcl9iYXNlNjR1cmxfbG9uZ2VyX2Zvcm1hdA",
    "verification_policy":"hybrid_required",
    "exp": 1893456000
  }'

Hybrid token contract

AffixIO supports migration-safe token verification with explicit algorithm and policy fields.

Request/Token shape

{
  "token_id": "tok_01HV...",
  "subject": "user_123",
  "claims": { "decision": 1 },
  "alg_classical": "Ed25519 | ECDSA_P256",
  "alg_pq": "Dilithium2 | Dilithium3",
  "sig_classical": "base64url",
  "sig_pq": "base64url",
  "verification_policy": "classical_only | pq_only | hybrid_required",
  "iat": 1710000000,
  "exp": 1710003600
}

Verification policy semantics

Policy	Verification rule	Recommended use
classical_only	Validate `sig_classical` only	Legacy partner migration
pq_only	Validate `sig_pq` only	PQ-native internal systems
hybrid_required	Validate both signatures; fail closed if either fails	Enterprise/government production default

Transport and size guidance

Dilithium signatures are much larger than classical signatures. For reliability, place hybrid tokens in request body or secure cookies, not request headers.

Recommended transport

Channel	Status	Notes
JSON body	Recommended	No tight per-header limits; easiest for large PQ payloads
HttpOnly cookie	Recommended	Use `Secure`, `HttpOnly`, `SameSite`; single-cookie practical limit is ~4 KB, split if required
Authorization header	Avoid for hybrid tokens	Many proxies/LBs enforce 4-8 KB header ceilings

Safe sizing profile

Item	Guideline
Single request header	Keep under 4 KB
Total request headers	Keep under 8 KB unless infra is explicitly tuned
Single cookie value	Keep under 4 KB practical limit
Hybrid token payload	Budget 4-6 KB end-to-end after encoding

Infrastructure defaults to validate

Confirm load balancer, CDN, API gateway, and app server header limits before enabling header transport for PQ/hybrid payloads.

# NGINX baseline profile for large auth metadata (review with Ops)
client_header_buffer_size 4k;
large_client_header_buffers 8 16k;

# If any upstream/proxy layer enforces smaller limits, requests may still fail.
# Keep hybrid signatures in JSON body or secure cookies when possible.

Performance benchmark disclosure

Separate native cryptographic operation timings from ZK proving and proof verification to prevent ambiguous claims.

Stage	Operation	p50	p95	Payload size	Hardware profile
Native	Classical sign/verify	--	--	--	CPU model, cores, RAM, runtime
Native	PQ sign/verify (Dilithium)	--	--	pubkey/signature bytes	CPU model, cores, RAM, runtime
ZK	Witness generation	--	--	circuit inputs bytes	prover backend + machine profile
ZK	Proof generation	--	--	proof bytes	prover backend + machine profile
ZK	Proof verification	--	--	proof bytes	verifier runtime profile
Example	PQ verify (dev baseline, non-ZK)	6.7 ms	9.8 ms	~2.4 KB signature	Publish exact CPU/runtime with each report

Endpoints

Method	Path	Purpose	State
GET	/health	Health check	Implemented
GET	/openapi.json	OpenAPI schema	Implemented
GET	/metrics	Platform metrics	Implemented
POST	/api-keys	Create API key	Implemented
POST	/agents	Create agent	Implemented
POST	/devices	Create device	Implemented
POST	/verify	Verification decision	Implemented
POST	/proofs/generate	Generate proof	Implemented
POST	/proofs/verify	Verify proof	Implemented
POST	/nior/policy/decide	NIOR policy decision	Implemented
POST	/tokens/generate-quantum-safe	Hybrid or PQ token generation with explicit verification policy	Implemented
POST	/tokens/validate-quantum-safe	Hybrid/PQ token validation (policy + envelope verification)	Implemented
POST	/offline/transactions	Offline placeholder route	501

Architecture intent

Read Why PQ signature + ZK audit for when to use PQ signatures alone, and when to layer ZK audit proofs for compliance and privacy requirements.

Errors

Status	Meaning
400	Invalid request
401	Missing/invalid API key
404	Not found
409	State conflict
422	Validation error
429	Rate limited
501	Mounted but not implemented