Input schema (JSON)
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Human-readable name for the key. Example: 'Home Assistant', 'CI Pipeline'."
},
"scope": {
"enum": [
"content_only",
"admin"
],
"type": "string",
"default": "content_only",
"description": "Scope for the key: 'content_only' (send content, list displays) or 'admin' (full management)."
},
"org_id": {
"type": "string",
"description": "Optional organization ID. If set, the key acts on behalf of this organization."
},
"permissions": {
"enum": [
"read",
"write",
"read_write"
],
"type": "string",
"default": "read_write",
"description": "Granular permission flag: 'read', 'write', or 'read_write' (default). Applied on top of 'scope' — e.g. a content_only read-only key cannot PUT data slots. Matched against HTTP verb: GET requires read, PUT/POST/PATCH/DELETE require write."
},
"access_token": {
"type": "string",
"description": "Optional bearer token; prefer session_request_id."
},
"capabilities": {
"type": "array",
"items": {
"enum": [
"slot.read",
"slot.write",
"display.read",
"display.send",
"display.manage"
],
"type": "string"
},
"description": "Optional JSON array of fine-grained capability flags this key may exercise. Allowed values: 'slot.read' (list/get slots), 'slot.write' (put/delete slots), 'display.read' (list/get displays, read content), 'display.send' (send_html/send_url/broadcast/clear/set_idle), 'display.manage' (rename/delete/lock/configure/license/pair/claim/create). Omit or pass [] for no capability restriction. Capabilities narrow — never expand — the key's rights; they combine with scope, permissions, and resource whitelists."
},
"expires_in_days": {
"type": "integer",
"description": "Optional expiration in days. If not set, the key never expires."
},
"allowed_slot_slugs": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 64,
"description": "Optional JSON array of data-slot slugs this key may touch (max 64). When set, every data-slot request must target one of these slugs. Omit or pass [] for no slug restriction. Example: ['sensor-lobby', 'sensor-garage']."
},
"session_request_id": {
"type": "string",
"description": "Session handle from create_auth_session; pass it on every authenticated call."
},
"allowed_display_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{8}$"
},
"maxItems": 64,
"description": "Optional JSON array of display profile IDs this key may touch (max 64). When set, every display request must target one of these IDs. Omit or pass [] for no display restriction. Example: ['ABCD1234','EFGH5678']."
}
}
}