Authentication

API keys, JWT tokens, capability scopes, and rate limits

API Keys

Every request requires a valid API key in the Authorization header

curl https://api.sandbox.zexrail.com/v1/agents \
  -H "Authorization: Bearer sk_test_your_api_key"

Sandbox keys use the sk_test_ prefix; production keys use sk_live_
Keys are scoped to a single environment and cannot cross boundaries
Rotate keys from the console dashboard without downtime

JWT Tokens

Short-lived tokens for agent-to-agent communication

curl -X POST https://api.sandbox.zexrail.com/v1/auth/token \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_abc123", "scopes": ["negotiation.create"]}'

JWTs expire after the configured TTL (default: 1 hour, max: 24 hours)
Scopes must be a subset of the API key capabilities
Tokens are RS256-signed and verified by every service

Capabilities (21 scopes)

Fine-grained permissions assigned to API keys and JWT tokens

agent.registeragent.readagent.updateagent.deletenegotiation.createnegotiation.readnegotiation.respondnegotiation.cancelsettlement.createsettlement.readsettlement.executesettlement.reversereceipt.readreceipt.listverity.verifyverity.investigatewebhook.createwebhook.readwebhook.updatewebhook.deletegovernance.dispute

Rate Limits

Requests per minute by plan tier

Tier	Requests/min	Burst	Daily Limit
Free	60	10	1,000
Pro	600	100	50,000
Enterprise	6,000	1,000	Unlimited

Rate limit headers included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.