Getting Started

AuthRAI API

The AuthRAI API gives your AI agents short-lived, scoped credentials instead of permanent API keys. Agents issue a token before each task — the token encodes exactly what it can do and for how long, signed with Ed25519.

Base URL

https://api.authrai.tech

Authentication

All API requests require your organisation API key in the Authorization header:

Authorization: Bearer ag_live_sk_...

Create API keys in the dashboard under API Keys. Keys are prefixed ag_live_ in production.

Errors

All errors return a JSON object with a detail field:

{
  "detail": "Token has expired"
}

Status	Meaning
400	Bad request — check field validation in the detail message
401	Missing or invalid API key
402	Trial expired or payment required
403	Account suspended or insufficient role
404	Resource not found
422	Validation error — body field mismatch
429	Rate limit exceeded
502/503	Upstream error (Paddle, SMTP)

Agents

An agent is a registered AI process with its own Ed25519 keypair and identity. Register once; issue tokens per task.

POST/v1/agentsRegister an agent

Generates a new Ed25519 keypair and registers the agent in your organisation. Returns the private key once — store it immediately.

Request body

Field	Type	Required	Description
name	string	✱	Human-readable agent name (max 256 chars)
owner	string	✱	Team or service that owns this agent
description	string		What this agent does
model_provider	string		e.g. openai, anthropic
model_name	string		e.g. gpt-4o, claude-3-5-sonnet
framework	string		e.g. langchain, autogen, custom

{
  "name": "order-processor-v2",
  "owner": "ops-team",
  "model_provider": "openai",
  "model_name": "gpt-4o"
}

GET/v1/agentsList agents

Query param	Type	Description
status	string	Filter: active, paused, revoked
limit	int	Max results (default 50)
offset	int	Pagination offset

DELETE/v1/agents/{agent_id}Revoke agent

Sets agent status to revoked. All active tokens for this agent are immediately invalidated.

Tokens

Task-scoped credentials issued per operation. Call POST /v1/tokens before each task; pass the token to downstream services which verify it at POST /v1/tokens/verify.

POST/v1/tokensIssue token

Field	Type	Required	Description
agent_id	string	✱	ID returned when the agent was registered
scope	string[]	✱	Actions this token may perform
ttl	int		Seconds until expiry (default 300, max 86400)
target_service	string		Downstream service name this token is for
intent	string		Human-readable task description for the audit log

# Request
{
  "agent_id": "ag_agent_abc123",
  "scope": ["orders.read", "payments.create"],
  "ttl": 300,
  "intent": "Process order #4892"
}

# Response
{
  "token": "ag_tok_eyJ...",
  "expires_at": "2025-06-22T10:05:00Z",
  "scope": ["orders.read", "payments.create"]
}

POST/v1/tokens/verifyVerify token — no auth required

Call from your downstream service to verify a token is valid, unexpired, and has the required scope. This endpoint requires no API key — it's designed to be called by services that receive tokens from agents.

# Request
{
  "token": "ag_tok_eyJ...",
  "required_scope": "orders.read"
}

# Response — valid
{ "valid": true, "agent_id": "ag_agent_abc123" }
# Response — invalid
{ "valid": false, "reason": "Token has expired" }

POST/v1/tokens/{token_id}/revokeRevoke token

Immediately invalidates a token before its natural expiry. Verified and audit-logged.

POST/v1/tokens/bulk-verifyVerify up to 50 tokens

Batch verification for high-throughput services. Returns a result object keyed by token.

{ "tokens": ["ag_tok_abc", "ag_tok_xyz"], "required_scope": "database.read" }

Policies

Allow/deny/throttle rules evaluated at token issuance. Higher priority wins. Use wildcard patterns to match scope families.

POST/v1/policiesCreate policy

{
  "name": "block-secrets-in-trial",
  "priority": 100,
  "rules": [{
    "action": "deny",
    "scope_pattern": "secrets.*"
  }]
}

Valid actions: allow, deny, throttle, require_approval.

PATCH/v1/policies/{policy_id}Update policy

{ "is_active": false }   // deactivate without deleting

Audit Log

SHA-256 hash-chained event trail. Tamper-evident — every event includes the hash of the previous event.

GET/v1/auditQuery events

Query param	Default	Description
hours	24	Lookback window in hours
limit	50	Max results
offset	0	Pagination offset
agent_id	—	Filter by agent ID
agent_name	—	Filter by agent name substring
event_type	—	Filter by event type (e.g. token.denied)
show_all	false	Include system events

GET/v1/audit/exportExport CSV / JSON

GET /v1/audit/export?format=csv&hours=720
GET /v1/audit/export?format=json&hours=24&event_type=token.denied

API Keys

Organisation-level keys for authenticating API calls. Create multiple keys for different services or environments.

GET/v1/account/keysList keys

Returns all keys — full key value is never returned after creation.

POST/v1/account/keysCreate key

{ "name": "ci-deploy" }

Returns the full key value once. Store it immediately.

DELETE/v1/account/keys/{key_id}Delete key

Permanently deletes the key. Cannot be undone.

Webhooks

Receive real-time events via HTTP POST to your endpoint. Every delivery includes an X-AmpGate-Signature: sha256=<hex> header. Verify it before trusting the payload.

POST/v1/webhooksRegister endpoint

{ "url": "https://your-server.com/hooks/authrai", "events": ["token.denied"] }

Leave events empty to receive all event types.

POST/v1/webhooks/{webhook_id}/testSend test event

Delivers a test.ping event to verify your endpoint is reachable.

GET/v1/webhooksList endpoints

DELETE/v1/webhooks/{webhook_id}Delete endpoint

Verify webhook signatures (Python)

import hmac, hashlib

def verify_authrai_webhook(payload: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Domain Verification

Verified domains allow agents to be scoped to specific origin services. Add a DNS TXT record to verify ownership.

POST/v1/webhooks/domainsAdd domain

{ "domain": "yourcompany.com" }

Returns a txt_record_name and txt_record_value to add to your DNS.

POST/v1/webhooks/domains/{domain_id}/verifyTrigger verification

Performs a live DNS lookup. DNS changes can take up to 48h.