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 /agents Register a new agent

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

Request Body

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-4", "claude-3"
framework	string		e.g., "langchain", "autogen"

Response

201 Created

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

GET /agents List all agents

Returns a paginated list of agents.

Query Parameters

Field	Type	Default	Description
limit	int	20	Max results per page
offset	int	0	Pagination offset
status	string		Filter by status: active, paused, revoked

DELETE /agents/:id Revoke an agent

Revokes an agent. All active tokens for this agent are immediately invalidated.

Tokens

POST /tokens Issue a scoped token

Issues a short-lived, scoped token for an agent. Tokens are cryptographically signed with Ed25519.

Request Body

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

201 Created

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

POST /tokens/verify Verify a token's validity

Verifies a token's signature, expiration, and scope. This endpoint does not require authentication — it's designed to be called by your services receiving tokens.

Verification is <5ms and requires no database lookup.

Request Body

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/:id Revoke a token

Immediately invalidates a token. Subsequent verifications will return invalid.

POST /tokens/bulk-verify Verify multiple tokens

Verify up to 100 tokens in a single request.

Policies

POST /policies Create a policy

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

Request Body

Field	Type	Required	Description
name	string	Yes	Policy name
description	string		Description
priority	int		Higher wins (0-10000, default: 100)
rules	array	Yes	Array of rule objects
is_active	bool		Activation state (default: true)

PATCH /policies/:id Update a policy

Update policy fields. Use is_active to toggle without opening a modal.

Audit Log

GET /audit Query audit events

Query audit log events. Events are hash-chained and tamper-proof.

GET /audit/export Export audit log

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

API Keys

POST /api-keys Create API key

Create a new API key for programmatic access.

GET /api-keys List API keys

List all API keys (values are masked).

DELETE /api-keys/:id Delete API key

Permanently delete an API key.

Webhooks

POST /webhooks Register 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 /webhooks List webhook endpoints

List all registered webhook endpoints.

Verified Domains

POST /domains Add domain for verification

Add a domain for DNS verification. Returns TXT record details.

POST /domains/:id/verify Check domain verification

Trigger a verification check for a pending domain.