API keys API
API keys endpoints in the Brix REST API: 4 operations (GET, POST, DELETE). Each lists its path, auth, required permission and a curl example.
View as Markdown · For AI agents: the full docs index is at /llms.txt
Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.
Every 4xx and 5xx response below returns this body:
| Field | Type | Description |
|---|---|---|
error | string | Machine-readable code: unauthorized, forbidden, not_found, validation_error, conflict, rate_limited, internal_error, … |
message | string | Human-readable explanation. Safe to show an operator. |
requestId | string | Present on 5xx: quote it to support. |
GET /v1/api-keys
Returns the workspace's API keys: name, assigned permissions, the location the key is pinned to (if any), and when each was created and last used. Key secrets are never returned. A key is listed only where the caller holds the API key view permission at the key's location; a workspace-wide key needs that permission for the whole workspace.
Notes.
- Not paginated. Revoked keys are listed too (revokedAt set).
curl "https://api.brixsignage.com/v1/api-keys" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | array of ApiKey | |
data[].id | string | |
data[].name | string | |
data[].preview | string | The first characters of the key (ak_us_live_Ab3x), to recognise it. Not usable as a credential. |
data[].permissions | "all" | array of string | resource.action permissions, or "all" (every permission, now and later). |
data[].nodeId | string | null | The location the key is pinned to (it can act only there and below). Null = workspace-wide. |
data[].lastUsedAt | string | null | |
data[].expiresAt | string | null | Null = never expires. |
data[].expired | boolean | |
data[].revokedAt | string | null | Set when the key was revoked; a revoked key no longer authenticates. |
data[].createdAt | string | ISO-8601 timestamp (UTC). |
Response 401: Missing, expired or revoked bearer token.
Response 403: The token lacks the permission this operation needs (see x-brix-permission).
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/api-keys
Creates a new API key. Provide name, permissions (a list of resource.action strings, or "all"), and an optional nodeId to restrict the key to one location and everything beneath it. The raw key secret is returned exactly once, in this response; only its hash is stored afterward, so it cannot be retrieved again.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
permissions | "all" | array of string | no | You must hold each one where the key applies. Default [] (a key that can do nothing). |
nodeId | string | null | no | Pin the key to this location. Omit for a workspace-wide key, which needs its permissions workspace-wide. |
expiresInDays | number | null | no | Days until the key stops working (at most 3650). Omit, null or 0 = never expires. |
curl -X POST "https://api.brixsignage.com/v1/api-keys" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Menu board sync","permissions":["screen.view","media.create"],"expiresInDays":365}'Response 201: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.name | string | |
data.preview | string | The first characters of the key (ak_us_live_Ab3x), to recognise it. Not usable as a credential. |
data.permissions | "all" | array of string | resource.action permissions, or "all" (every permission, now and later). |
data.nodeId | string | null | The location the key is pinned to (it can act only there and below). Null = workspace-wide. |
data.lastUsedAt | string | null | |
data.expiresAt | string | null | Null = never expires. |
data.expired | boolean | |
data.revokedAt | string | null | Set when the key was revoked; a revoked key no longer authenticates. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.secret | string | The full key. Shown ONLY in this response; store it now. Send it as Authorization: Bearer <secret>. |
Response 401: Missing, expired or revoked bearer token.
Response 403: You do not hold every permission you grant, or not at the key's location (a workspace-wide key needs them workspace-wide). Also refused for a Brix support session.
Response 422: name missing, expiresInDays over 3650 or not a number, or nodeId not a location of this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
DELETE /v1/api-keys/{id}
Revokes an API key immediately, so it can no longer be used. You must hold the permission to delete keys at or above the location the key is pinned to, not merely somewhere else in the workspace.
Notes.
- The key stays in the list with revokedAt set. Revoking a key again answers 200 and moves revokedAt to now.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | API key id. |
curl -X DELETE "https://api.brixsignage.com/v1/api-keys/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.revoked | true |
Response 401: Missing, expired or revoked bearer token.
Response 403: You lack api-key.delete at the key's location.
Response 404: No such key in this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/api-keys/{id}/rotate
Replaces an API key's secret with a new one, invalidating the old secret immediately. The new secret is returned exactly once, in this response. You must hold the permission to create keys at or above the location the key is pinned to.
Notes.
- The key keeps its id, name, permissions, location and expiry; lastUsedAt is reset to null. An expired key can be rotated and stays expired.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | API key id. |
curl -X POST "https://api.brixsignage.com/v1/api-keys/{id}/rotate" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.name | string | |
data.preview | string | The first characters of the key (ak_us_live_Ab3x), to recognise it. Not usable as a credential. |
data.permissions | "all" | array of string | resource.action permissions, or "all" (every permission, now and later). |
data.nodeId | string | null | The location the key is pinned to (it can act only there and below). Null = workspace-wide. |
data.lastUsedAt | string | null | |
data.expiresAt | string | null | Null = never expires. |
data.expired | boolean | |
data.revokedAt | string | null | Set when the key was revoked; a revoked key no longer authenticates. |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.secret | string | The full key. Shown ONLY in this response; store it now. Send it as Authorization: Bearer <secret>. |
Response 401: Missing, expired or revoked bearer token.
Response 403: The key holds permissions you cannot grant at its location, you lack api-key.create there, or a Brix support session.
Response 404: No such key in this workspace.
Response 409: revoked: a revoked key cannot be rotated; create a new one.
Response 5XX: Server error. The body carries a requestId to quote to support.