v1 API

Authentication

All endpoints (except /api/v1/user/exchangeToken and /api/v1/health) require authentication via API key passed in the X-API-Key header.

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/user/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
X-API-Key: <API_KEY>
```

Example Response:

[
    {
        "uuid": "0186e56d-7000-7000-8040-940f030080ad",
        "timestamp": 1678886400,
        "user": "user.123",
        "item": "task.456",
        "action": "create",
        "payload": "{}"
    },
    {
        "uuid": "0186e56d-73e8-7000-8012-51aacd3dbf8e",
        "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.

Example Request:

POST /api/v1/events
X-API-Key: <API_KEY>
Content-Type: application/json

[
    {
        "uuid": "0186e56d-77d0-7000-8003-c289bf62cf41",
        "timestamp": 1678886402,
        "user": "user.123",
        "item": "item.789",
        "action": "create",
        "payload": "{}"
    }
]

Example Response:

[
    {
        "uuid": "0186e56d-7000-7000-8040-940f030080ad",
        "timestamp": 1678886400,
        "user": "user.123",
        "item": "item.456",
        "action": "create",
        "payload": "{}"
    },
    {
        "uuid": "0186e56d-73e8-7000-8012-51aacd3dbf8e",
        "timestamp": 1678886401,
        "user": "user.123",
        "item": "item.456",
        "action": "update",
        "payload": "{\"title\": \"New Title\"}"
    },
    {
        "uuid": "0186e56d-77d0-7000-8003-c289bf62cf41",
        "timestamp": 1678886402,
        "user": "user.123",
        "item": "item.789",
        "action": "create",
        "payload": "{}"
    }
]

ACL Management

`POST /api/v1/acl`

Purpose: Submit new ACL rules.
Method: POST
Authentication: Required (API key)
Request:
- A JSON array of ACL rules.
Response:
- Success (200 OK): ACL rules submitted successfully.
- Bad Request (400 Bad Request): Invalid ACL rule.
- Unauthorized (401 Unauthorized): Invalid API key.
- Forbidden (403 Forbidden): Insufficient permissions.
ACL Validation: User must have appropriate permissions on the .acl item to submit ACL rules.

Example Request:

POST /api/v1/acl
X-API-Key: <API_KEY>
Content-Type: application/json

[{
    "user": "user.456",
    "item": "item.789",
    "action": "read",
    "type": "allow"
}]

Example Response:
```
{
    "message": "ACL events submitted"
}
```

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 Authentication

`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:
- JSON body with user (required) - 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
X-API-Key: <ADMIN_API_KEY>
Content-Type: application/json

{
    "user": "user.123"
}

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:
- JSON body with user (required) - 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
X-API-Key: <ADMIN_API_KEY>
Content-Type: application/json

{
    "user": "user.123"
}

Example Response:

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

`POST /api/v1/user/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/user/exchangeToken
Content-Type: application/json

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

Example Response:

{
    "keyUuid": "0199ab65-1a1e-7000-80f5-23a591c5106e",
    "apiKey": "sk_abcdefghijklmnopqrstuvwxyz1234567890",
    "user": "user.123",
    "description": "Desktop Client"
}