📚 ACT Documentation

Quick Start

Get up and running with ACT in 5 minutes:

curl -X POST https://api.acttokens.com/v1/agents \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI Agent",
    "description": "Description of your agent"
  }'

curl -X POST https://api.acttokens.com/v1/policies \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read-Only Policy",
    "actions": ["read", "list"],
    "resources": ["api://database/*"],
    "effect": "allow"
  }'

curl -X POST https://api.acttokens.com/v1/tokens \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123",
    "expiresIn": 3600
  }'

curl -X POST https://api.acttokens.com/v1/enforce \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "uuid",
    "capabilityToken": "token_from_step_4",
    "action": "read",
    "resourceId": "api://database/users",
    "tenantId": "default-tenant"
  }'

Core Concepts

Authentication & Authorization

Overview

ACT uses a dual-token authentication model:

How It Works

Analogy: API Key is like your company's access card to enter the building. Capability Token is like a specific employee's badge showing which floors/rooms they can access.

Request Flow

# 1. Create Agent (Platform Auth Only)
curl -X POST https://api.acttokens.com/v1/agents \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent"}'

# 2. Create Policy (Platform Auth Only)
curl -X POST https://api.acttokens.com/v1/policies \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Policy", "actions": ["read"]}'

# 3. Issue Token (Platform Auth → Get Capability Token)
curl -X POST https://api.acttokens.com/v1/tokens \
  -H "X-Api-Key: your_api_key" \
  -d '{"agentId": "agent_123", "expiresIn": 3600}'
Response: {"token": "eyJhbGc..."}  # Capability Token

# 4. Enforce Policy (Both Tokens!)
curl -X POST https://api.acttokens.com/v1/enforce \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilityToken": "eyJhbGc...",
    "action": "read",
    "resourceId": "api://data"
  }'

Security Best Practices

• Protect API Key: Never commit to version control. Use environment variables or secret managers.
• Short-lived Tokens: Issue capability tokens with 1-hour expiration and implement refresh logic.
• Rotate Keys: Rotate API keys quarterly. Revoke old keys immediately after rotation.
• Fail Secure: If ACT is unavailable, deny access by default (never allow without validation).
• Monitor Usage: Track token usage in audit logs for anomalies.

Agents API

Manage AI agents in your system.

Create Agent

{
  "name": "string",
  "description": "string",
  "metadata": { "custom_field": "value" }
}

Get Agent

List Agents

Update Agent

Delete Agent

Policies API

Create and manage security policies.

Create Policy

{
  "name": "string",
  "actions": ["read", "write"],
  "resources": ["api://resource/*"],
  "effect": "allow",
  "constraints": {}
}

Get Policy

List Policies

Update Policy

Assign Policy to Agent

Tokens API

Issue and manage capability tokens.

Issue Token

{
  "agentId": "string",
  "expiresIn": 3600
}

Validate Token

Enforcement API

The core endpoint for policy enforcement.

Enforce Policy

{
  "requestId": "uuid",
  "capabilityToken": "token",
  "action": "read",
  "resourceId": "api://resource/id",
  "tenantId": "tenant_id",
  "context": {}
}

Audit Logs API

Retrieve audit logs for compliance and monitoring.

Get Audit Logs

Query Parameters:

• agentId - Filter by agent
• startTime - ISO 8601 timestamp
• endTime - ISO 8601 timestamp
• limit - Number of results (default: 100)

Security Best Practices

Performance Optimization

Enforcement Latency: Most enforcement calls complete in <100ms.

Caching: You can cache enforcement decisions for 30-60 seconds, but refresh on token rotation.

Batch Operations: For high-volume scenarios, batch multiple enforcement calls if possible.

Rate Limits: Standard tier allows 1000 requests/minute. Contact support for higher limits.

Monitoring

Health Check: GET /health returns 200 OK when the API is healthy.

Metrics: All API responses include metrics headers:

• X-Response-Time - Request processing time in ms
• X-Request-Id - Unique request identifier

Alerts: Monitor enforcement decision distribution (allowed vs denied) to detect policy issues.