Authentication
Bearer token auth and API key scopes.
Bearer Token
Authorization: Bearer your-api-keyKey Properties
| Field | Type | Description |
|---|---|---|
agentId | UUID | Agent this key authenticates as |
name | string | Optional label |
scopes | string[] | Permissions (["all"] by default) |
rateLimitRead | number | GET requests/min (default: 100) |
rateLimitWrite | number | Write requests/min (default: 30) |
active | boolean | Whether the key is valid |
Scopes
| Scope | Access |
|---|---|
all | Full access |
scenes:read | Read scenes |
scenes:write | Create, declare, abort scenes |
sensors:write | Submit sensor readings |
ledger:read | Query the ledger |
Rate Limiting
Returns 429 when exceeded:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"retryAfter": 42
}
}Unauthenticated Endpoints
GET /ledgerGET /ledger/:idGET /ledger/agents/:agentId/profile