Brix API Keys API

openapi: 3.2.0
info:
  title: Brix API Keys API
  version: '1'
  summary: 'Control plane for Brix digital signage: screens, content, playlists, schedules, casts and emergencies.'
  description: 'Generated from the route table the API actually mounts

    (`apps/api/routes.snapshot.json`), the description each route is required to

    carry (`tests/contracts/route-registry.json`), and request/response schemas

    (`apps/api/src/openapi/`). CI enforces all three, so this document cannot list a

    route that does not exist or omit one that does.


    **Schemas.** 447 operations carry request and response schemas

    (`x-brix-schema: verified`). Each is checked in CI against the response the

    real handler returns — a missing, mistyped or undeclared field fails the build.

    The remaining operations are route-level only (`x-brix-schema: none`): their

    path, method, permission and purpose are exact, but the shape of `data` is not

    yet modelled, and we would rather say so than publish a schema that validates

    against nothing. Objects are open: a new field is not a breaking change.


    **Envelope.** Success bodies are `{ "data": … }`. Failures are

    `{ "error": "", "message": "…" }`, plus `requestId` on a 5xx.

    Many list routes page opt-in (see each operation): pass `?limit=` and

    follow `nextCursor` via `?cursor=` until it is null.


    **Authentication.** `Authorization: Bearer ` with an API key

    (`ak_…`, created in the console under Settings → API & MCP) or a user session. An

    API key carries a creator-chosen set of `resource.verb` permissions and may be

    pinned to one location''s subtree; a key can never be granted a permission its

    creator does not hold. The permission an operation needs is in

    `x-brix-permission` and in its security requirement.


    **Tenancy.** Every request resolves to one workspace. A resource belonging to

    another tenant returns 404, never 403, so a response never confirms that an

    account exists.


    **Rate limits.** A 429 carries `Retry-After`; a 503 `database_busy` means retry

    after the `Retry-After` interval.'
servers:
- url: https://api.brixsignage.com
  description: Production
security:
- bearerAuth: []
tags:
- name: API Keys
paths:
  /v1/api-keys:
    get:
      operationId: listApiKeys
      tags:
      - API Keys
      summary: List API keys
      description: '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).'
      x-brix-permission: api-key.view
      x-brix-schema: verified
      x-brix-notes:
      - Not paginated. Revoked keys are listed too (`revokedAt` set).
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - api-key.view
    post:
      operationId: createApiKey
      tags:
      - API Keys
      summary: Create API key
      description: 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.
      x-brix-permission: api-key.create
      x-brix-schema: verified
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                permissions:
                  description: You must hold each one where the key applies. Default `[]` (a key that can do nothing).
                  anyOf:
                  - type: string
                    const: all
                  - type: array
                    items:
                      type: string
                nodeId:
                  description: Pin the key to this location. Omit for a workspace-wide key, which needs its permissions workspace-wide.
                  anyOf:
                  - type: string
                  - type: 'null'
                expiresInDays:
                  description: Days until the key stops working (at most 3650). Omit, null or 0 = never expires.
                  anyOf:
                  - type: number
                  - type: 'null'
              required:
              - name
            example:
              name: Menu board sync
              permissions:
              - screen.view
              - media.create
              expiresInDays: 365
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      preview:
                        type: string
                        description: The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential.
                      permissions:
                        anyOf:
                        - type: string
                          const: all
                        - type: array
                          items:
                            type: string
                        description: '`resource.action` permissions, or `"all"` (every permission, now and later).'
                      nodeId:
                        anyOf:
                        - type: string
                        - type: 'null'
                        description: The location the key is pinned to (it can act only there and below). Null = workspace-wide.
                      lastUsedAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                      expiresAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                        description: Null = never expires.
                      expired:
                        type: boolean
                      revokedAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                        description: Set when the key was revoked; a revoked key no longer authenticates.
                      createdAt:
                        type: string
                        description: ISO-8601 timestamp (UTC).
                      secret:
                        type: string
                        description: 'The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer <secret>`.'
                    required:
                    - id
                    - name
                    - preview
                    - permissions
                    - nodeId
                    - lastUsedAt
                    - expiresAt
                    - expired
                    - revokedAt
                    - createdAt
                    - secret
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`name` missing, `expiresInDays` over 3650 or not a number, or `nodeId` not a location of this workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - api-key.create
  /v1/api-keys/{id}:
    delete:
      operationId: deleteApiKey
      tags:
      - API Keys
      summary: Revoke API key
      description: '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.'
      x-brix-permission: api-key.delete
      x-brix-schema: verified
      x-brix-notes:
      - The key stays in the list with `revokedAt` set. Revoking a key again answers 200 and moves `revokedAt` to now.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: API key id.
        example: ak_7a8b9c0d1e2f3a4b
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      revoked:
                        type: boolean
                        const: true
                    required:
                    - id
                    - revoked
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: You lack `api-key.delete` at the key's location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such key in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - api-key.delete
  /v1/api-keys/{id}/rotate:
    post:
      operationId: rotateApiKey
      tags:
      - API Keys
      summary: Rotate API key
      description: '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.'
      x-brix-permission: api-key.create
      x-brix-schema: verified
      x-brix-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.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: API key id.
        example: ak_7a8b9c0d1e2f3a4b
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      preview:
                        type: string
                        description: The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential.
                      permissions:
                        anyOf:
                        - type: string
                          const: all
                        - type: array
                          items:
                            type: string
                        description: '`resource.action` permissions, or `"all"` (every permission, now and later).'
                      nodeId:
                        anyOf:
                        - type: string
                        - type: 'null'
                        description: The location the key is pinned to (it can act only there and below). Null = workspace-wide.
                      lastUsedAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                      expiresAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                        description: Null = never expires.
                      expired:
                        type: boolean
                      revokedAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                        description: Set when the key was revoked; a revoked key no longer authenticates.
                      createdAt:
                        type: string
                        description: ISO-8601 timestamp (UTC).
                      secret:
                        type: string
                        description: 'The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer <secret>`.'
                    required:
                    - id
                    - name
                    - preview
                    - permissions
                    - nodeId
                    - lastUsedAt
                    - expiresAt
                    - expired
                    - revokedAt
                    - createdAt
                    - secret
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key holds permissions you cannot grant at its location, you lack `api-key.create` there, or a Brix support session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such key in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`revoked`: a revoked key cannot be rotated; create a new one.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - api-key.create
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: 'Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …'
        message:
          description: Human-readable explanation. Safe to show an operator.
          type: string
        requestId:
          description: 'Present on 5xx: quote it to support.'
          type: string
      required:
      - error
      additionalProperties: {}
      description: Error envelope returned by every failing request.
    ApiKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        preview:
          type: string
          description: The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential.
        permissions:
          anyOf:
          - type: string
            const: all
          - type: array
            items:
              type: string
          description: '`resource.action` permissions, or `"all"` (every permission, now and later).'
        nodeId:
          anyOf:
          - type: string
          - type: 'null'
          description: The location the key is pinned to (it can act only there and below). Null = workspace-wide.
        lastUsedAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
        expiresAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
          description: Null = never expires.
        expired:
          type: boolean
        revokedAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
          description: Set when the key was revoked; a revoked key no longer authenticates.
        createdAt:
          type: string
          description: ISO-8601 timestamp (UTC).
      required:
      - id
      - name
      - preview
      - permissions
      - nodeId
      - lastUsedAt
      - expiresAt
      - expired
      - revokedAt
      - createdAt
      description: An API key. The secret is never returned after creation or rotation.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.