RomM Permissions API

openapi: 3.2.0
info:
  title: RomM Permissions API
  version: 5.4.0
tags:
- name: Permissions
paths:
  /api/permissions/me:
    get:
      tags:
      - Permissions
      summary: Get My Permissions
      description: 'Return the caller''s effective permissions for the UI to gate on.


        The backend remains the source of truth; this is a UX hint. Includes the

        granted action keys and the platform/rom ids hidden from the caller.'
      operationId: get_my_permissions_api_permissions_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsResponse'
      security:
      - OAuth2PasswordBearer:
        - me.read
      - HTTPBasic: []
  /api/permissions/catalog:
    get:
      tags:
      - Permissions
      summary: Get Permission Catalog
      description: The entity/action vocabulary the admin UI renders its matrix from.
      operationId: get_permission_catalog_api_permissions_catalog_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionCatalogSchema'
      security:
      - OAuth2PasswordBearer:
        - users.read
      - HTTPBasic: []
  /api/permissions/groups:
    get:
      tags:
      - Permissions
      summary: List Permission Groups
      description: List all permission groups with their grants.
      operationId: list_permission_groups_api_permissions_groups_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PermissionGroupSchema'
                type: array
                title: Response List Permission Groups Api Permissions Groups Get
      security:
      - OAuth2PasswordBearer:
        - users.read
      - HTTPBasic: []
    post:
      tags:
      - Permissions
      summary: Create Permission Group
      description: Create a permission group.
      operationId: create_permission_group_api_permissions_groups_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionGroupCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionGroupSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer:
        - users.write
      - HTTPBasic: []
  /api/permissions/groups/{id}:
    put:
      tags:
      - Permissions
      summary: Update Permission Group
      description: Update a permission group (name/description/default/grants).
      operationId: update_permission_group_api_permissions_groups__id__put
      security:
      - OAuth2PasswordBearer:
        - users.write
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionGroupUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionGroupSchema'
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Permissions
      summary: Delete Permission Group
      description: Delete a permission group. Members fall back to the default group.
      operationId: delete_permission_group_api_permissions_groups__id__delete
      security:
      - OAuth2PasswordBearer:
        - users.write
      - HTTPBasic: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/permissions/users/{user_id}:
    get:
      tags:
      - Permissions
      summary: Get User Permissions
      description: A user's group membership, per-user overrides and hidden entities.
      operationId: get_user_permissions_api_permissions_users__user_id__get
      security:
      - OAuth2PasswordBearer:
        - users.read
      - HTTPBasic: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPermissionsSchema'
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Permissions
      summary: Update User Permissions
      description: Assign a user's group and/or replace their per-user overrides.
      operationId: update_user_permissions_api_permissions_users__user_id__put
      security:
      - OAuth2PasswordBearer:
        - users.write
      - HTTPBasic: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPermissionsUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPermissionsSchema'
        '404':
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/permissions/hidden:
    post:
      tags:
      - Permissions
      summary: Add Hidden Entity
      description: Hide an entity from a user OR a group (exactly one principal).
      operationId: add_hidden_entity_api_permissions_hidden_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HiddenEntityCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HiddenEntitySchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer:
        - users.write
      - HTTPBasic: []
    delete:
      tags:
      - Permissions
      summary: Remove Hidden Entity
      description: Un-hide an entity for a user OR a group.
      operationId: remove_hidden_entity_api_permissions_hidden_delete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_remove_hidden_entity_api_permissions_hidden_delete'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer:
        - users.write
      - HTTPBasic: []
components:
  schemas:
    PermissionGroupCreate:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
        is_default:
          type: boolean
          title: Is Default
          default: false
        color:
          anyOf:
          - type: string
          - type: 'null'
          title: Color
        grants:
          items:
            $ref: '#/components/schemas/GrantSchemaIO'
          type: array
          title: Grants
          default: []
        age_limit:
          anyOf:
          - type: integer
            maximum: 21.0
            minimum: 0.0
          - type: 'null'
          title: Age Limit
        hide_unrated_roms:
          type: boolean
          title: Hide Unrated Roms
          default: false
      type: object
      required:
      - name
      title: PermissionGroupCreate
    UserPermissionsSchema:
      properties:
        user_id:
          type: integer
          title: User Id
        permission_group_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Permission Group Id
        overrides:
          items:
            $ref: '#/components/schemas/OverrideSchemaIO'
          type: array
          title: Overrides
        hidden:
          items:
            $ref: '#/components/schemas/HiddenEntitySchema'
          type: array
          title: Hidden
        age_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Age Limit
        hide_unrated_roms:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hide Unrated Roms
      type: object
      required:
      - user_id
      - permission_group_id
      - overrides
      - hidden
      title: UserPermissionsSchema
      description: Admin view of one user's permission assignment.
    PermAction:
      type: string
      enum:
      - read
      - write
      - delete
      title: PermAction
    PermEntity:
      type: string
      enum:
      - platforms
      - roms
      - collections
      - playlists
      - firmware
      - assets
      - devices
      - users
      - tasks
      - logs
      - streaming
      - emulation
      title: PermEntity
      description: 'Entity-type vocabulary for granular permissions.


        Mirrors the coarse scope domains (see ``handler/auth/constants.py``) so the

        grant matrix can be projected back onto the legacy ``Scope`` set without

        drift (see ``handler/auth/permissions_map.py``).'
    Body_remove_hidden_entity_api_permissions_hidden_delete:
      properties:
        entity:
          $ref: '#/components/schemas/PermEntity'
        entity_id:
          type: integer
          title: Entity Id
        user_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: User Id
        group_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Group Id
      type: object
      required:
      - entity
      - entity_id
      title: Body_remove_hidden_entity_api_permissions_hidden_delete
    HiddenEntitiesSchema:
      properties:
        platforms:
          items:
            type: integer
          type: array
          title: Platforms
        roms:
          items:
            type: integer
          type: array
          title: Roms
      type: object
      required:
      - platforms
      - roms
      title: HiddenEntitiesSchema
    GrantSchema:
      properties:
        action:
          $ref: '#/components/schemas/ActionKey'
        scope:
          $ref: '#/components/schemas/PermissionScopeSchema'
      type: object
      required:
      - action
      - scope
      title: GrantSchema
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PermissionGroupUpdate:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        is_default:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Default
        color:
          anyOf:
          - type: string
          - type: 'null'
          title: Color
        grants:
          anyOf:
          - items:
              $ref: '#/components/schemas/GrantSchemaIO'
            type: array
          - type: 'null'
          title: Grants
        age_limit:
          anyOf:
          - type: integer
            maximum: 21.0
            minimum: 0.0
          - type: 'null'
          title: Age Limit
        hide_unrated_roms:
          type: boolean
          title: Hide Unrated Roms
          default: false
        set_age_settings:
          type: boolean
          title: Set Age Settings
          default: false
      type: object
      title: PermissionGroupUpdate
    PermissionsResponse:
      properties:
        is_admin:
          type: boolean
          title: Is Admin
        grants:
          items:
            $ref: '#/components/schemas/GrantSchema'
          type: array
          title: Grants
        hidden:
          $ref: '#/components/schemas/HiddenEntitiesSchema'
      type: object
      required:
      - is_admin
      - grants
      - hidden
      title: PermissionsResponse
    GrantSchemaIO:
      properties:
        entity:
          $ref: '#/components/schemas/PermEntity'
        action:
          $ref: '#/components/schemas/PermAction'
        own_only:
          type: boolean
          title: Own Only
          default: false
      type: object
      required:
      - entity
      - action
      title: GrantSchemaIO
      description: A single (entity, action) grant on a group, with the own-only flag.
    UserPermissionsUpdate:
      properties:
        permission_group_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Permission Group Id
        set_group:
          type: boolean
          title: Set Group
          default: false
        overrides:
          anyOf:
          - items:
              $ref: '#/components/schemas/OverrideSchemaIO'
            type: array
          - type: 'null'
          title: Overrides
        age_limit:
          anyOf:
          - type: integer
            maximum: 21.0
            minimum: 0.0
          - type: 'null'
          title: Age Limit
        hide_unrated_roms:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hide Unrated Roms
        set_age_settings:
          type: boolean
          title: Set Age Settings
          default: false
      type: object
      title: UserPermissionsUpdate
    PermissionGroupSchema:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        is_default:
          type: boolean
          title: Is Default
        system_key:
          anyOf:
          - $ref: '#/components/schemas/SystemGroupKey'
          - type: 'null'
        color:
          anyOf:
          - type: string
          - type: 'null'
          title: Color
        grants:
          items:
            $ref: '#/components/schemas/GrantSchemaIO'
          type: array
          title: Grants
        member_count:
          type: integer
          title: Member Count
        hidden:
          items:
            $ref: '#/components/schemas/HiddenEntitySchema'
          type: array
          title: Hidden
          default: []
        age_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Age Limit
        hide_unrated_roms:
          type: boolean
          title: Hide Unrated Roms
          default: false
      type: object
      required:
      - id
      - name
      - description
      - is_default
      - system_key
      - color
      - grants
      - member_count
      title: PermissionGroupSchema
    OverrideSchemaIO:
      properties:
        entity:
          $ref: '#/components/schemas/PermEntity'
        action:
          $ref: '#/components/schemas/PermAction'
        granted:
          type: boolean
          title: Granted
        own_only:
          type: boolean
          title: Own Only
          default: false
      type: object
      required:
      - entity
      - action
      - granted
      title: OverrideSchemaIO
    PermissionCatalogSchema:
      properties:
        entities:
          items:
            $ref: '#/components/schemas/PermEntity'
          type: array
          title: Entities
        actions:
          items:
            $ref: '#/components/schemas/PermAction'
          type: array
          title: Actions
      type: object
      required:
      - entities
      - actions
      title: PermissionCatalogSchema
      description: The vocabulary the admin UI renders the group/override matrix from.
    SystemGroupKey:
      type: string
      enum:
      - viewer
      - editor
      title: SystemGroupKey
    HiddenEntitySchema:
      properties:
        entity:
          $ref: '#/components/schemas/PermEntity'
        entity_id:
          type: integer
          title: Entity Id
      type: object
      required:
      - entity
      - entity_id
      title: HiddenEntitySchema
    HiddenEntityCreate:
      properties:
        entity:
          $ref: '#/components/schemas/PermEntity'
        entity_id:
          type: integer
          title: Entity Id
        user_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: User Id
        group_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Group Id
      type: object
      required:
      - entity
      - entity_id
      title: HiddenEntityCreate
    PermissionScopeSchema:
      properties:
        kind:
          type: string
          enum:
          - global
          - platform
          - collection
          - rom
          title: Kind
          default: global
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
      type: object
      title: PermissionScopeSchema
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ActionKey:
      type: string
      enum:
      - rom.view
      - rom.play
      - rom.download
      - rom.upload
      - rom.edit
      - rom.delete
      - rom.match
      - rom.refresh
      - rom.favorite
      - platform.view
      - platform.create
      - platform.edit
      - platform.delete
      - collection.view
      - collection.create
      - collection.edit
      - collection.delete
      - playlist.edit
      - library.scan
      - stream.start
      - netplay.host
      - user.view
      - user.create
      - user.edit
      - user.delete
      - app.admin
      title: ActionKey
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes:
            me.read: View your profile
            roms.read: View ROMs
            platforms.read: View platforms
            assets.read: View assets
            devices.read: View devices
            firmware.read: View firmware
            roms.user.read: View user-rom properties
            collections.read: View collections
            playlists.read: View music playlists
            me.write: Modify your profile
            assets.write: Modify assets
            devices.write: Modify devices
            roms.user.write: Modify user-rom properties
            collections.write: Modify collections
            playlists.write: Modify music playlists
            roms.write: Modify ROMs
            platforms.write: Modify platforms
            firmware.write: Modify firmware
            users.read: View users
            users.write: Modify users
            tasks.run: Run tasks
            logs.read: View backend logs
          tokenUrl: /token
    HTTPBasic:
      type: http
      scheme: basic