Brix OAuth API

openapi: 3.2.0
info:
  title: Brix OAuth 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: OAuth
paths:
  /v1/oauth/register:
    post:
      operationId: createOauthRegister
      tags:
      - OAuth
      summary: Register an OAuth client
      description: 'Registers a public OAuth client (dynamic client registration, RFC 7591) that uses PKCE and no client secret. Redirect URIs must use https, or http on the local computer. A registered client belongs to no workspace and can do nothing until a person approves a connection. This endpoint is rate-limited per IP address.


        **Notes.**

        - RFC 7591 dynamic client registration for apps that connect to the MCP endpoint. No `{ data }` envelope. The client can do nothing until a person approves a connection.'
      x-brix-schema: verified
      x-brix-notes:
      - RFC 7591 dynamic client registration for apps that connect to the MCP endpoint. No `{ data }` envelope. The client can do nothing until a person approves a connection.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                redirect_uris:
                  type: array
                  items:
                    type: string
                  description: '1–10 URIs: https, or http on a loopback address.'
                client_name:
                  type: string
                client_uri:
                  description: https only.
                  type: string
                logo_uri:
                  description: https only.
                  type: string
                token_endpoint_auth_method:
                  description: Only public clients (PKCE, no secret).
                  type: string
                  const: none
              required:
              - redirect_uris
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                  client_id_issued_at:
                    type: integer
                    description: Unix seconds.
                  client_name:
                    type: string
                    description: Defaults to the first redirect URI's host.
                  redirect_uris:
                    type: array
                    items:
                      type: string
                  client_uri:
                    type: string
                  logo_uri:
                    type: string
                  grant_types:
                    type: array
                    items:
                      type: string
                  response_types:
                    type: array
                    items:
                      type: string
                  token_endpoint_auth_method:
                    type: string
                    const: none
                required:
                - client_id
                - client_id_issued_at
                - client_name
                - redirect_uris
                - grant_types
                - response_types
                - token_endpoint_auth_method
        '400':
          description: 'OAuth error body: `invalid_redirect_uri` or `invalid_client_metadata`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 20 registrations a minute from one address.
          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: []
  /v1/oauth/revoke:
    post:
      operationId: createOauthRevoke
      tags:
      - OAuth
      summary: Revoke an OAuth token
      description: 'Revokes a refresh token or an MCP access token (RFC 7009). This ends the whole connection: every access token of that connection stops working on its next request. Always answers 200.


        **Notes.**

        - RFC 7009: always 200 with an empty body, whether or not the token was valid. Revoking ends the whole connection. An access token minted from an API key (client credentials) is not revoked here: revoke the API key.'
      x-brix-schema: verified
      x-brix-notes:
      - 'RFC 7009: always 200 with an empty body, whether or not the token was valid. Revoking ends the whole connection. An access token minted from an API key (client credentials) is not revoked here: revoke the API key.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: A refresh token or a connected app's access token.
                client_id:
                  description: The client the token was issued to.
                  type: string
              required:
              - token
      responses:
        '200':
          description: Success; no body.
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests from one address.
          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: []
  /v1/oauth/token:
    post:
      operationId: createOauthToken
      tags:
      - OAuth
      summary: Get an access token
      description: 'Exchanges an API key for an OAuth 2.0 access token using the client-credentials grant: `client_id` is the API key''s id and `client_secret` is the key''s secret. The returned token is a reference to the key rather than a copy of its permissions, so revoking the key immediately invalidates every token issued from it, and any permission change takes effect on the token''s next use without needing a refresh. Responses follow the OAuth specification, including `invalid_client` on an authentication failure and `unsupported_grant_type` for an unsupported grant. This endpoint is rate-limited per IP address.


        **Notes.**

        - RFC 6749: no `{ data }` envelope, and errors use OAuth''s `error` + `error_description`.

        - The schema shown is the client-credentials answer. The `authorization_code` and `refresh_token` grants serve apps connected by a person (MCP) and also return `refresh_token`.'
      x-brix-schema: verified
      x-brix-notes:
      - 'RFC 6749: no `{ data }` envelope, and errors use OAuth''s `error` + `error_description`.'
      - The schema shown is the client-credentials answer. The `authorization_code` and `refresh_token` grants serve apps connected by a person (MCP) and also return `refresh_token`.
      x-brix-credential: 'OAuth client credentials: `client_id` = the API key''s id, `client_secret` = the API key, in the form body or as HTTP Basic.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                  - authorization_code
                  - refresh_token
                client_id:
                  description: 'Client credentials: the API key''s id (or send HTTP Basic).'
                  type: string
                client_secret:
                  description: 'Client credentials: the API key (or send HTTP Basic).'
                  type: string
                scope:
                  description: Space-separated permissions; only those the key holds are granted.
                  type: string
                code:
                  description: '`authorization_code` (connected apps).'
                  type: string
                code_verifier:
                  description: '`authorization_code`: the PKCE verifier.'
                  type: string
                redirect_uri:
                  description: '`authorization_code`.'
                  type: string
                refresh_token:
                  description: '`refresh_token`.'
                  type: string
              required:
              - grant_type
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: 'Send as `Authorization: Bearer …`. It acts with the API key''s live permissions.'
                  token_type:
                    type: string
                    const: Bearer
                  expires_in:
                    type: integer
                    description: Seconds.
                  scope:
                    type: string
                    description: The granted permissions (`all` for a full-access key).
                required:
                - access_token
                - token_type
                - expires_in
                - scope
        '400':
          description: 'OAuth error body (`error`, `error_description`): `invalid_request`, `unsupported_grant_type`, `invalid_grant`, …'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`invalid_client`: the key id and key do not match, or the key is revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 30 client-credential requests in 5 minutes from one address.
          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: []
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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.