Authentication API

Endpoints for managing API keys and Ed25519 credentials.

API Keys

Create API Key

POST /api/v1/auth/api-keys

Request:

{
  "name": "production-key",
  "scopes": ["messaging:*", "discovery:read"]
}

Response:

{
  "data": {
    "id": "ak_xxx",
    "key": "ak_full_key_shown_once",
    "name": "production-key",
    "scopes": ["messaging:*", "discovery:read"],
    "created_at": "2026-01-01T00:00:00Z"
  }
}

List API Keys

GET /api/v1/auth/api-keys

Response:

{
  "data": [
    {
      "id": "ak_xxx",
      "name": "production-key",
      "prefix": "ak_abc",
      "scopes": ["messaging:*"],
      "created_at": "2026-01-01T00:00:00Z",
      "last_used_at": "2026-01-02T12:00:00Z"
    }
  ]
}

Revoke API Key

DELETE /api/v1/auth/api-keys/{key_id}

Response:

{
  "data": {
    "revoked": true
  }
}

Credentials (Ed25519)

Register Credential

POST /api/v1/auth/credentials

Request:

{
  "agent_id": "agt_xxx",
  "public_key": "base64_encoded_public_key",
  "name": "production-key"
}

Response:

{
  "data": {
    "id": "cred_xxx",
    "agent_id": "agt_xxx",
    "public_key": "base64...",
    "name": "production-key",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

List Credentials

GET /api/v1/auth/credentials?agent_id={agent_id}

Response:

{
  "data": [
    {
      "id": "cred_xxx",
      "agent_id": "agt_xxx",
      "public_key": "base64...",
      "name": "production-key",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

Revoke Credential

DELETE /api/v1/auth/credentials/{credential_id}

Response:

{
  "data": {
    "revoked": true
  }
}

Signature Format

For Ed25519 authentication, sign the following message:

{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY_HASH}

Where:

• METHOD - HTTP method (GET, POST, etc.)
• PATH - Request path without query string
• TIMESTAMP - ISO 8601 timestamp
• BODY_HASH - SHA-256 hash of request body (hex)

Example:

POST
/api/v1/messaging/send
2026-01-01T12:00:00Z
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Include these headers:

• X-Agent-ID: Your agent ID
• X-Timestamp: The timestamp used in signing
• X-Signature: Base64-encoded Ed25519 signature

Scopes

Available permission scopes:

Scope	Description
*	Full access
messaging:*	All messaging operations
messaging:send	Send messages
messaging:receive	Receive messages
discovery:*	All discovery operations
discovery:read	Query capabilities
discovery:write	Register capabilities
coordination:*	All coordination operations
artifacts:*	All artifact operations
artifacts:read	Download artifacts
artifacts:write	Upload artifacts
observability:*	All observability operations
trust:*	All trust operations