Consumption tracking

The consumption API lets backend services record arbitrary numeric usage metrics (API calls, bytes stored, seats used, etc.) per user per application. Aggregates are stored in a dedicated table and can be read back — or reset — via the admin API.

Authentication

The consumption write endpoint accepts two forms of authentication:

1. client_credentials access token — a Bearer token issued by the OAuth client_credentials grant for the application. This is the recommended approach for server-to-server calls.
2. Admin session cookie — an active session with the admin or superadmin role.

Any other request receives 403 CONS_004.

Record consumption

POST /api/consumption
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "applicationId": "<app-uuid>",
  "userId": "<user-id>",
  "key": "api.calls",
  "value": 10
}

Both a raw entry (in consumptionEntries) and a running aggregate (in consumptionAggregates) are written atomically. The aggregate is updated with an ON CONFLICT … DO UPDATE upsert. Returns 404 CONS_003 if the user has no access record for the application.

Read aggregates

GET /api/consumption/:userId/:appId

Returns the latest aggregate for every key the user has recorded for the application:

{
  "aggregates": [
    { "key": "api.calls", "value": "1540", "updatedAt": "2026-04-12T10:00:00Z" },
    { "key": "storage.bytes", "value": "52428800", "updatedAt": "2026-04-11T15:30:00Z" }
  ]
}

value is returned as a string because the underlying column uses numeric (arbitrary precision). Parse with parseFloat() or a decimal library.

Reset a counter

Admin only (requires admin session — client_credentials tokens are not accepted for DELETE):

DELETE /api/consumption/:userId/:appId/:key

Deletes all raw entries and the aggregate row for the given userId + appId + key combination.