MA
MachineAuth

Agents

An Agent is an autonomous identity that can authenticate and access your APIs.

What is an Agent?

An agent represents an AI or machine that needs to access your APIs. Each agent has:

  • Unique client_id (public identifier)
  • Private client_secret (shown once)
  • Assigned scopes (permissions)
  • Optional organization_id and team_id

Agent Lifecycle

Created → Active → (Rotation) → (Deactivation) → (Reactivation) → Active
                            ↘
                             → Deleted

Create an Agent

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "scopes": ["read", "write"],
    "organization_id": "org_123",
    "team_id": "team_456",
    "expires_in": 7776000
  }'

Response:

{
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-agent",
    "client_id": "cid_abc123...",
    "scopes": ["read", "write"],
    "is_active": true,
    "created_at": "2026-03-01T12:00:00Z",
    "expires_at": "2026-06-01T12:00:00Z"
  },
  "client_id": "cid_abc123...",
  "client_secret": "cs_secret..."
}

Agent Fields

| Field | Type | Description | |-------|------|-------------| | id | UUID | Unique identifier | | name | string | Human-readable name | | client_id | string | Public identifier | | client_secret | string | Private secret (only on create) | | scopes | array | Granted permissions | | organization_id | string | Associated org | | team_id | UUID | Associated team | | is_active | boolean | Whether agent can get tokens | | expires_at | timestamp | Optional expiration | | token_count | integer | Tokens issued | | refresh_count | integer | Tokens refreshed | | last_activity_at | timestamp | Last API call |

Credential Rotation

Rotate an agent's secret:

curl -X POST http://localhost:8080/api/agents/AGENT_ID \
  -H "Content-Type: application/json" \
  -d '{"action": "rotate"}'

The old secret immediately stops working. Existing tokens remain valid until expiry.

Agent Self-Service

Agents can manage themselves using their JWT:

# Get own profile
curl http://localhost:8080/api/agents/me \
  -H "Authorization: Bearer TOKEN"

# Get usage stats
curl http://localhost:8080/api/agents/me/usage \
  -H "Authorization: Bearer TOKEN"

# Rotate own credentials
curl -X POST http://localhost:8080/api/agents/me/rotate \
  -H "Authorization: Bearer TOKEN"

# Deactivate self
curl -X POST http://localhost:8080/api/agents/me/deactivate \
  -H "Authorization: Bearer TOKEN"

# Reactivate self
curl -X POST http://localhost:8080/api/agents/me/reactivate \
  -H "Authorization: Bearer TOKEN"

# Delete self
curl -X DELETE http://localhost:8080/api/agents/me/delete \
  -H "Authorization: Bearer TOKEN"

Next Steps