Zoca Staff Roles API

openapi: 3.2.0
info:
  title: Zoca Platform Staff Roles API
  description: 'The Zoca platform API behind the Zoca web app and mobile apps: scheduling, website generation, Google Business Profile, discovery/local SEO, social media, booking enquiries, offers, clients, staff, billing and the Zoca "brain" agent layer.'
  version: 3.20.10
  contact: {}
  x-apievangelist-note: Harvested verbatim from https://api.zoca.ai/swagger.json. The provider ships the default NestJS Swagger metadata (title "API Documentation", empty servers[]); title/description/servers were set by API Evangelist for identification and the unmodified original is preserved at openapi/_original/zoca-platform-swagger.json. Every path, operation, summary, parameter and response is exactly as published.
servers:
- url: https://api.zoca.ai
  description: Production
tags:
- name: Staff Roles
paths:
  /staff/roles:
    get:
      description: Returns staff-assignable service-provider roles (`SP` and `SP_*`) plus this business’ custom permission sets. Customer, guest, internal, legacy business, and other businesses’ custom records are excluded.
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Array of role records.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing `staff:read` scope.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: List staff roles and permission sets available at a business.
      tags:
      - Staff Roles
    post:
      description: Enforces `uq_roles_name_entity` (`(entityId, name)`) — same name at same business returns 409. `scopes` keys are validated against `USER_PERMISSION_VALUES`.
      operationId: t_value
      parameters: []
      responses:
        '201':
          description: Role created.
        '400':
          description: Validation error (unknown scope, mass-assignment, etc).
        '401':
          description: Unauthenticated.
        '403':
          description: Missing `modifyStaffRoles` scope.
        '409':
          description: Role name already exists at this business.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Create a per-business custom role.
      tags:
      - Staff Roles
  /staff/roles/{roleId}:
    patch:
      description: Bumps `presetVersion` and fans out to every un-modified `auth.user_roles` row (spec §2.1 Flow 6). Built-in (SYSTEM) roles cannot be patched — 403.
      operationId: t_value[0]
      parameters: []
      responses:
        '200':
          description: Updated role record.
        '400':
          description: Validation error.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing scope OR built-in role.
        '404':
          description: Role not found.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Replace the scope preset on a custom role.
      tags:
      - Staff Roles
    delete:
      description: Hard-DELETE on `auth.roles` cascades to assignment rows. Built-in roles are protected (403). Response includes the count of unassigned users for UI summary.
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Role deleted.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing scope OR built-in role.
        '404':
          description: Role not found.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Delete a custom role (cascades to `auth.user_roles`).
      tags:
      - Staff Roles
  /staff/roles/{roleId}/scopes:
    patch:
      description: Bumps `presetVersion` and fans out to every un-modified `auth.user_roles` row (spec §2.1 Flow 6). Built-in (SYSTEM) roles cannot be patched — 403.
      operationId: t_value[1]
      parameters: []
      responses:
        '200':
          description: Updated role record.
        '400':
          description: Validation error.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing scope OR built-in role.
        '404':
          description: Role not found.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Replace the scope preset on a custom role.
      tags:
      - Staff Roles
  /staff/roles/assignments:
    post:
      description: Captures `appliedPresetVersion` at assign time (snapshot semantics per FC-ST-10). `permissionsModifiedFromRole` starts false and flips when overrides land later.
      operationId: t_value
      parameters: []
      responses:
        '201':
          description: Assignment created.
        '400':
          description: Validation error.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing `manageStaffPermissions` scope.
        '404':
          description: Role not found.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Assign a role to a user at a business.
      tags:
      - Staff Roles
    put:
      description: Revokes existing BUSINESS_ENTITY assignments for the (user, business) pair, then assigns the new role. Used by the Overview role select.
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Role set.
        '400':
          description: Validation error.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing `manageStaffPermissions` scope.
        '404':
          description: Role not found.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Set (replace) a user's role at a business.
      tags:
      - Staff Roles
  /staff/roles/assignments/{userRoleId}:
    delete:
      description: Idempotent. The 5-minute permission cache TTL flushes any stale effective-scope reads; explicit cache invalidation lands in W5.2 observability wiring.
      operationId: t_value
      parameters: []
      responses:
        '204':
          description: Revoked.
        '401':
          description: Unauthenticated.
        '403':
          description: Missing `manageStaffPermissions` scope.
        '503':
          description: Feature disabled (killswitch).
      security:
      - bearer: []
      summary: Revoke a `auth.user_roles` assignment by id.
      tags:
      - Staff Roles
components:
  securitySchemes:
    access-token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      name: Authorization
      description: Enter JWT token in the format Bearer <token>
      in: header