API Reference

Complete REST API reference for ClawAuth. All endpoints use JSON and require HTTPS.

Base URL

https://api.clawauth.com

All API requests must be made over HTTPS. HTTP requests will be rejected.

🔗 Interactive API Documentation

Explore and test the API endpoints directly in your browser using our Swagger UI:

Open Swagger UI →

Authentication

ClawAuth uses different authentication methods for different types of requests:

Service API Key: For service operations (Bearer token)
Agent JWT: For agent-specific operations
Human JWT: For registration and management operations

Authentication headers

# Service authentication
Authorization: Bearer svc_abc123...

# Agent authentication  
Authorization: Bearer eyJhbGciOiJFUzI1Ni...

# Human authentication
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

Agent Authentication Endpoints

POST /auth/register

POST /auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "My AI Agent",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
}

Response 201:
{
  "agentId": "agent_abc123",
  "publicKeyHash": "sha256:1234abcd...",
  "status": "active"
}

POST /auth/challenge

Request a cryptographic challenge for authentication.

Request challenge

POST /auth/challenge
Content-Type: application/json

{
  "agentId": "agent_abc123"
}

Response 200:
{
  "challengeId": "chal_xyz789",
  "nonce": "1234567890abcdef...",
  "expiresAt": "2026-02-09T14:30:00Z"
}

POST /auth/authenticate

Complete authentication by submitting signed challenge.

Complete authentication

POST /auth/authenticate
Content-Type: application/json

{
  "challengeId": "chal_xyz789",
  "signature": "30440220123abc..."
}

Response 200:
{
  "accessToken": "eyJhbGciOiJFUzI1Ni...",
  "refreshToken": "rf_abc123...",
  "expiresIn": 3600
}

POST /auth/refresh

Refresh access token using refresh token.

Refresh token

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "rf_abc123..."
}

Response 200:
{
  "accessToken": "eyJhbGciOiJFUzI1Ni...",
  "refreshToken": "rf_def456...",
  "expiresIn": 3600
}

Service Management Endpoints

GET /services/:serviceId/verify

Verify an agent JWT token.

Verify agent token

GET /services/svc_123/verify
Authorization: Bearer svc_api_key_456
X-Agent-Token: Bearer eyJhbGciOiJFUzI1Ni...

Response 200:
{
  "valid": true,
  "agent": {
    "id": "agent_abc123",
    "name": "My AI Agent",
    "trustScore": 8.7,
    "roles": ["user", "api_access"],
    "permissions": ["read", "write"]
  }
}

GET /services/:serviceId/agents/:agentId

Get detailed agent information.

Get agent info

GET /services/svc_123/agents/agent_abc123
Authorization: Bearer svc_api_key_456

Response 200:
{
  "id": "agent_abc123",
  "name": "My AI Agent",
  "publicKeyHash": "sha256:1234abcd...",
  "status": "active",
  "trustScore": 8.7,
  "metadata": {},
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-02-09T12:00:00Z",
  "lastSeenAt": "2026-02-09T13:00:00Z"
}

POST /services/:serviceId/agents/:agentId/roles

Assign a role to an agent.

Assign role

POST /services/svc_123/agents/agent_abc123/roles
Authorization: Bearer svc_api_key_456
Content-Type: application/json

{
  "roleId": "admin",
  "expiresAt": "2026-12-31T23:59:59Z"
}

Response 200:
{
  "assigned": true
}

DELETE /services/:serviceId/agents/:agentId/roles/:roleId

Revoke a role from an agent.

Revoke role

DELETE /services/svc_123/agents/agent_abc123/roles/admin
Authorization: Bearer svc_api_key_456

Response 200:
{
  "revoked": true
}

Trust System Endpoints

POST /trust/feedback

Submit trust feedback for an agent.

Submit trust feedback

POST /trust/feedback
Authorization: Bearer svc_api_key_456
Content-Type: application/json

{
  "agentId": "agent_abc123",
  "score": 8.5,
  "reason": "Excellent API usage patterns",
  "metadata": {
    "category": "api_usage",
    "duration_minutes": 30
  }
}

Response 200:
{
  "recorded": true,
  "newTrustScore": 8.6
}

GET /trust/agents/:agentId/history

Get trust score history for an agent.

Get trust history

GET /trust/agents/agent_abc123/history?limit=10
Authorization: Bearer svc_api_key_456

Response 200:
{
  "data": [
    {
      "id": "feedback_xyz789",
      "serviceId": "svc_123",
      "score": 8.5,
      "reason": "Good performance",
      "metadata": {},
      "createdAt": "2026-02-09T12:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 45,
    "hasMore": true
  }
}

Role Management Endpoints

POST /services/:serviceId/roles

Create a new role for your service.

Create role

POST /services/svc_123/roles
Authorization: Bearer svc_api_key_456
Content-Type: application/json

{
  "name": "power_user",
  "description": "Power users with extended API access",
  "permissions": ["read", "write", "admin_read"]
}

Response 201:
{
  "roleId": "role_abc123",
  "name": "power_user",
  "permissions": ["read", "write", "admin_read"]
}

GET /services/:serviceId/roles

List all roles for your service.

List roles

GET /services/svc_123/roles
Authorization: Bearer svc_api_key_456

Response 200:
{
  "data": [
    {
      "id": "role_abc123",
      "name": "admin",
      "description": "Full administrative access",
      "permissions": ["read", "write", "admin", "manage_users"],
      "createdAt": "2026-01-01T00:00:00Z"
    },
    {
      "id": "role_def456",
      "name": "user",
      "description": "Basic user access",
      "permissions": ["read"],
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Health & Status Endpoints

GET /health

Check API health status.

Health check

GET /health

Response 200:
{
  "status": "healthy",
  "timestamp": "2026-02-09T13:00:00Z",
  "checks": {
    "database": "up",
    "redis": "up",
    "webhook_queue": "up"
  }
}

GET /status

Get API status and metrics (requires authentication).

Status endpoint

GET /status
Authorization: Bearer svc_api_key_456

Response 200:
{
  "version": "1.2.3",
  "uptime": 86400,
  "requestCount": 1234567,
  "activeServices": 42,
  "activeAgents": 1337
}

Error Responses

All errors follow a consistent format:

Error format

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Invalid or expired token",
    "details": {
      "reason": "token_expired",
      "expiredAt": "2026-02-09T12:00:00Z"
    }
  }
}

Common Error Codes

Code	Status	Description
AUTHENTICATION_FAILED	401	Invalid or missing authentication
INSUFFICIENT_PERMISSIONS	403	Operation not allowed for this agent
AGENT_NOT_FOUND	404	Agent does not exist
RATE_LIMIT_EXCEEDED	429	Too many requests
INVALID_SIGNATURE	400	Cryptographic signature is invalid

Rate Limits

ClawAuth enforces rate limits to ensure service reliability:

Endpoint Category	Limit	Window
Authentication (/auth/*)	10 requests	1 minute
Verification (/services/*/verify)	1000 requests	1 minute
Management (roles, agents)	100 requests	1 minute
Trust feedback	50 requests	1 minute

Webhooks

ClawAuth can send webhooks for important events:

Webhook payload example

{
  "event": "agent.authentication_failed",
  "timestamp": "2026-02-09T13:00:00Z",
  "data": {
    "agentId": "agent_abc123",
    "serviceId": "svc_456",
    "reason": "invalid_signature",
    "ipAddress": "192.168.1.1"
  }
}

Webhook Events

agent.authenticated - Successful agent authentication
agent.authentication_failed - Failed authentication attempt
agent.role_assigned - Role assigned to agent
agent.role_revoked - Role removed from agent
trust.feedback_received - Trust feedback submitted