Authentication

Moxxy uses bearer token authentication with scoped permissions.

Token Format

API tokens use the mox_ prefix and are stored as SHA-256 hashes in the database. The plaintext token is returned once at creation and never persisted.

Authorization: Bearer mox_abc123...

Auth Modes

Mode	Description
Loopback (default)	Requests from localhost (127.0.0.1, ::1) bypass token requirement
Token	All requests require a valid bearer token

Configure via MOXXY_LOOPBACK environment variable or auth_mode in ~/.moxxy/config/gateway.yaml.

Bootstrap Flow

The first token creation requires no authentication:

1. Gateway starts with no tokens in the database
2. POST /v1/auth/tokens succeeds without auth (bootstrap mode)
3. Subsequent token creation requires tokens:admin scope

Token Scopes

Scope	Description
agents:read	List and get agents
agents:write	Create agents, spawn sub-agents
runs:write	Start and stop runs
vault:read	List secrets
vault:write	Create and manage secrets and grants
tokens:admin	Create and revoke tokens
events:read	Stream SSE events
channels:read	List channels
channels:write	Create and manage channels
*	Wildcard -- all permissions

API Endpoints

Create Token

POST /v1/auth/tokens

Request:

{
  "scopes": ["agents:read", "agents:write", "runs:write"],
  "ttl": "2025-12-31T23:59:59Z"
}

Response:

{
  "id": "tok_abc123",
  "token": "mox_live_abc123...",
  "scopes": ["agents:read", "agents:write", "runs:write"],
  "expires_at": "2025-12-31T23:59:59Z",
  "created_at": "2025-01-15T10:00:00Z"
}

WARNING

The token field is only returned once. Store it securely.

List Tokens

GET /v1/auth/tokens

Response:

{
  "tokens": [
    {
      "id": "tok_abc123",
      "scopes": ["agents:read", "agents:write"],
      "status": "active",
      "expires_at": "2025-12-31T23:59:59Z",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Revoke Token

DELETE /v1/auth/tokens/{id}

Response:

{
  "id": "tok_abc123",
  "status": "revoked"
}

Token Lifecycle

Status	Description
active	Token is valid and can be used
revoked	Token has been explicitly revoked
expired	Token TTL has passed

Using Tokens

cURL

curl -H "Authorization: Bearer mox_your_token" \
  http://127.0.0.1:3000/v1/agents

JavaScript

const response = await fetch('http://127.0.0.1:3000/v1/agents', {
  headers: {
    'Authorization': 'Bearer mox_your_token'
  }
});

Python

import requests

response = requests.get(
    'http://127.0.0.1:3000/v1/agents',
    headers={'Authorization': 'Bearer mox_your_token'}
)

Environment Variable

Set a default token for CLI and API access:

export MOXXY_TOKEN="mox_your_token"

Security Notes

• Tokens are SHA-256 hashed before storage -- the database never contains plaintext tokens
• Token scopes are checked at the route handler level
• Loopback mode is intended for local development only
• For production or network-exposed deployments, disable loopback and use scoped tokens
• Revocation takes effect immediately