v1 API

Authentication

All endpoints (except /api/v1/setup/exchangeToken and /api/v1/health) require authentication via API key passed in the Authorization header as Bearer <API_KEY>.

API keys are obtained through the setup token exchange process:

An admin generates a setup token for a user via POST /api/v1/user/generateToken
The user exchanges the setup token for an API key via POST /api/v1/setup/exchangeToken
The API key is used for all subsequent authenticated requests

Setup tokens expire after 24 hours and can only be used once. Users can have multiple API keys for different clients/devices.

Events

`GET /api/v1/events`

Purpose: Retrieve the authoritative event history.
Method: GET
Request:
- No parameters
Response:
- Success (200 OK): A JSON array of event objects.
- Unauthorized (401 Unauthorized): If the user is not authenticated.

Example Request:

GET /api/v1/events
Authorization: Bearer <API_KEY>

Example Response:

[
    {
        "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "timestamp": 1678886400,
        "user": "user.123",
        "item": "task.456",
        "action": "create",
        "payload": "{}"
    },
    {
        "uuid": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
        "timestamp": 1678886401,
        "user": "user.123",
        "item": "task.456",
        "action": "update",
        "payload": "{\"title\": \"New Title\"}"
    }
]

`POST /api/v1/events`

Purpose: Push new events from the client to the server.
Method: POST
Request:
- A JSON array of event objects representing the new events.
Response:
- Success (200 OK): A JSON array of all event objects in the authoritative event history (after the new events have been applied and ACL validation).
- Unauthorized (401 Unauthorized): If the user is not authenticated.
ACL Validation: All incoming events are evaluated against current ACL. Events that violate the ACL are filtered out and not added to the history. See the ACL documentation for details.

Example Request:

POST /api/v1/events
Authorization: Bearer <API_KEY>
Content-Type: application/json

[
    {
        "uuid": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
        "timestamp": 1678886402,
        "user": "user.123",
        "item": "item.789",
        "action": "create",
        "payload": "{}"
    }
]

Example Response:

[
    {
        "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "timestamp": 1678886400,
        "user": "user.123",
        "item": "item.456",
        "action": "create",
        "payload": "{}"
    },
    {
        "uuid": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
        "timestamp": 1678886401,
        "user": "user.123",
        "item": "item.456",
        "action": "update",
        "payload": "{\"title\": \"New Title\"}"
    },
    {
        "uuid": "c3d4e5f6-a7b8-9012-3456-7890abcdef01",
        "timestamp": 1678886402,
        "user": "user.123",
        "item": "item.789",
        "action": "create",
        "payload": "{}"
    }
]

Health Check

`GET /api/v1/health`

Purpose: Check the health status of the service.
Method: GET
Request: None
Response:
- Success (200 OK): A JSON object containing the service health information.
Example Request:
```
GET /api/v1/health
```

Example Response:

{
    "status": "healthy",
    "timestamp": "2025-09-22T08:14:09Z",
    "version": "0.1.0",
    "uptime": 123
}

User Management

`POST /api/v1/user/resetKey`

Purpose: Invalidate all API keys for a user, requiring them to re-authenticate.
Method: POST
Authentication: Required (API key)
Request:
- Query parameter: user (string) - ID of the user whose API keys to invalidate
Response:
- Success (200 OK): Confirmation message
- Unauthorized (401): Insufficient permissions or invalid user
ACL: Requires .user.resetKey permission for the target user, or .root access

Example Request:

POST /api/v1/user/resetKey?user=user.123
Authorization: Bearer <ADMIN_API_KEY>

Example Response:

{
    "message": "API keys invalidated successfully"
}

`POST /api/v1/user/generateToken`

Purpose: Generate a setup token for a user.
Method: POST
Authentication: Required (API key)
Request:
- Query parameter: user (string) - ID of the user to generate setup token for
Response:
- Success (200 OK): Setup token information
- Unauthorized (401): Insufficient permissions or invalid user
ACL: Requires .user.generateToken permission for the target user, or .root access

Example Request:

POST /api/v1/user/generateToken?user=user.123
Authorization: Bearer <ADMIN_API_KEY>

Example Response:

{
    "token": "ABCD-1234",
    "expiresAt": "2025-09-26T12:00:00Z"
}

Setup

`POST /api/v1/setup/exchangeToken`

Purpose: Exchange a setup token for an API key.
Method: POST
Authentication: None (token-based)
Request:
- JSON body with token (required) and optional description
Response:
- Success (200 OK): API key information
- Unauthorized (401): Invalid, expired, or used token

Example Request:

POST /api/v1/setup/exchangeToken
Content-Type: application/json

{
    "token": "ABCD-1234",
    "description": "Desktop Client"
}

Example Response:

{
    "keyUuid": "550e8400-e29b-41d4-a716-446655440000",
    "apiKey": "sk_abcdefghijklmnopqrstuvwxyz1234567890",
    "user": "user.123",
    "description": "Desktop Client"
}