API tokens, credits and usage

My credit balance and latest entries

GET /api/v1/me/credits

The account’s credit balance and its latest ledger entries. Query parameter: before, to page back through older entries.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Response (200, JSON):

Field	Type	Required	Notes
available	integer	yes
balance	integer	yes
billingMode	string	yes
entries	array of object	yes
entries[].amount	integer	yes
entries[].createdAt	string	yes
entries[].id	integer	yes
entries[].kind	string	yes
entries[].meter	string	no
next	string	yes
rates	array of object	yes
rates[].creditsPerUnit	integer	yes
rates[].meter	string	yes
rates[].unit	string	yes
reserved	integer	yes
writeCost	integer	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/me/credits" \
  -b cookies.txt

My usage by app, meter and day

GET /api/v1/me/usage

What the account used, by app, meter and day.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Response (200, JSON):

Field	Type	Required	Notes
apps	array of object	yes
apps[].appId	string	yes
apps[].appName	string	yes
apps[].daily	array of object	yes
apps[].daily[].day	string	yes
apps[].daily[].meter	string	yes
apps[].daily[].quantity	integer	yes
apps[].totals	object	yes
days	integer	yes
notMeasured	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/me/usage" \
  -b cookies.txt

List my API tokens

GET /api/v1/tokens

The account’s API tokens: name, scopes, when each was made and when it expires. Never the secrets.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Response (200, JSON):

Field	Type	Required	Notes
tokens	array of object	yes
tokens[].createdAt	string	yes
tokens[].expiresAt	string	yes
tokens[].id	string	yes
tokens[].name	string	yes
tokens[].scopes	array of string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X GET "https://node.example.com/api/v1/tokens" \
  -b cookies.txt

Mint an API token

POST /api/v1/tokens

Makes an API token (oak_pat_…) for scripts. Its scopes are data:read, data:write, app::read or app::write. A token reaches the account’s own data in apps and no more, and never the account itself. The secret is in this response only.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Request body (JSON):

Field	Type	Required	Notes
expiresAt	string	no
name	string	yes
scopes	array of string	yes

Response (200, JSON):

Field	Type	Required	Notes
token	string	yes
tokenResponse	object	yes
tokenResponse.createdAt	string	yes
tokenResponse.expiresAt	string	yes
tokenResponse.id	string	yes
tokenResponse.name	string	yes
tokenResponse.scopes	array of string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/tokens" \
  -b cookies.txt -H "X-CSRF-Token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "scopes": []}'

Revoke an API token

DELETE /api/v1/tokens/{id}

Revokes an API token. Requests made with it fail from then on.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes).

Path parameters: id.

Response: no body on success.

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X DELETE "https://node.example.com/api/v1/tokens/{id}" \
  -b cookies.txt -H "X-CSRF-Token: $CSRF"