API Overview

The AuthRAI API lets you programmatically manage agents, issue and verify tokens, and configure policies. All endpoints use JSON for request and response bodies.

BASE URL
https://api.authrai.tech/v1

Authentication

All API requests require an API key in the Authorization header.

HEADER FORMAT

        Authorization: Bearer rai_pk_live_your_api_key_here

Generate API keys in your dashboard's API Keys page.

Security notes

Keep your API keys secret. Never expose them in client-side code.
Use separate keys for development and production environments.
Rotate keys if you suspect they've been compromised.

Errors

AuthRAI uses standard HTTP status codes to indicate success or failure.

Code	Status	Description
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid API key
402	Payment Required	Plan limit reached or quota exceeded
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
422	Unprocessable	Validation failed
429	Rate Limited	Too many requests
502	Bad Gateway	Upstream service error

Agents

POST/agentsRegister a new agent

Creates a new agent identity. Returns a secret key for signing token requests.

Field	Type	Required	Description
name	string	Yes	Human-readable name for the agent
owner	string	Yes	Team or service that owns this agent
description	string		Optional description
model_provider	string		e.g. "openai", "anthropic"
model_name	string		e.g. "gpt-4o", "claude-opus"
framework	string		e.g. "langchain", "autogen"

{
  "id": "agent_a1b2c3d4e5f6",
  "name": "data-processor",
  "owner": "engineering",
  "agent_secret_key": "sk_live_xK9mNp2...",
  "created_at": "2026-07-01T14:00:00Z"
}

GET/agentsList all agents

Returns a paginated list of agents. Supports status, limit, and offset query params.

DELETE/agents/:idRevoke an agent

Immediately stops all future token issuance for this agent.

Tokens

POST/tokensIssue a scoped token

Issues a short-lived, scoped token for an agent. Signed with Ed25519.

Field	Type	Required	Description
agent_id	string	Yes	ID of the agent requesting the token
scope	string[]	Yes	Array of scope strings
ttl	int		Seconds (default 300, max 86400)
target_service	string		Target service identifier (default "any")
task_description	string		Human-readable description of the task

{
  "token": "rai_live_xK9mNp2qRsT...",
  "agent_id": "agent_a1b2c3d4",
  "scope": ["secrets.read", "db.write"],
  "expires_at": "2026-07-01T14:05:00Z"
}

POST/tokens/verifyVerify a token's validity

Verifies a token's signature, expiration, and scope. Does not require authentication — designed to be called by services receiving tokens.

Verification is <5ms and requires no database lookup.

Field	Type	Required	Description
token	string	Yes	The token to verify
required_scope	string[]		Optional scope to check

Try it live

Token

Required scope (optional)

DELETE/tokens/:idRevoke a token

Immediately invalidates a token. Subsequent verifications return invalid.

POST/tokens/bulk-verifyVerify multiple tokens

Verify up to 100 tokens in a single request.

GET/tokens/pendingList pending approvals

Token requests held for manual approval under a policy's require_approval rule.

Policies

POST/policiesCreate a policy

Create a policy with rules for allowing, denying, or throttling token operations.

Field	Type	Required	Description
name	string	Yes	Policy name
priority	int		Higher evaluated first (default 0)
rules	array	Yes	Array of {effect, actions} objects
is_active	bool		Activation state (default true)

DELETE/policies/:idDeactivate a policy

Deactivates a policy. Policies are soft-deleted, never destroyed, to preserve the audit trail.

Audit Log

GET/auditQuery audit events

Query audit log events. Events are hash-chained (SHA-256) and tamper-evident.

GET/audit/verify-chainVerify chain integrity

Recomputes the hash chain over the requested range and confirms nothing has been altered.

GET/audit/exportExport audit log

Export as CSV or JSON. Use ?format=csv or ?format=json.

API Keys

POST/account/keysCreate API key

Create a new API key for programmatic access.

GET/account/keysList API keys

List all API keys. Values are masked after creation.

DELETE/account/keys/:idDelete API key

Permanently delete an API key.

Webhooks

POST/webhooksRegister webhook endpoint

Register a webhook endpoint. Returns a signing secret for verification.

AVAILABLE EVENTS

token.issued
token.denied
token.revoked
agent.created
agent.revoked
policy.created
policy.deactivated
billing.plan_upgraded

GET/webhooksList webhook endpoints

List all registered webhook endpoints.

POST/webhooks/:id/testSend a test event

Sends a signed test payload to confirm your endpoint is receiving and verifying deliveries correctly.

Verified Domains

POST/webhooks/domainsAdd domain for verification

Add a domain for DNS verification. Returns the TXT record to publish.

POST/webhooks/domains/:id/verifyCheck domain verification

Triggers a DNS lookup to check a pending domain's TXT record.