NimbusNexus V1:authz:permission:versioning API

openapi: 3.2.0
info:
  title: NimbusNexus API — External V1:authz:permission:versioning…
  description: 'External (public) API intended for client-facing integrations and the web portal.


    Authentication:

    - This API uses JWT Bearer authentication.

    - In Swagger UI, click ''Authorize'' and sign in via the configured token endpoint.

    - Swagger will automatically attach the header: Authorization: Bearer .'
  version: test
servers:
- url: /
  description: Current host
- url: https://fastapi.dev.nimbusnexus.net
  description: Development
security:
- SwaggerLogin: []
- ApiKeyAuth: []
tags:
- name: v1:authz:permission:versioning
paths:
  /api/v1/authz/permission/{rule_id}/versions:
    get:
      tags:
      - v1:authz:permission:versioning
      summary: List Versions
      description: Lists the version tree of a permission rule.
      operationId: list_versions_api_v1_authz_permission__rule_id__versions_get
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VersionNode'
                title: Response List Versions Api V1 Authz Permission  Rule Id  Versions Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{rule_id}/versions/{version}:
    get:
      tags:
      - v1:authz:permission:versioning
      summary: Get Version
      description: Retrieves the reconstructed snapshot of a permission rule at a specific version.
      operationId: get_version_api_v1_authz_permission__rule_id__versions__version__get
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{rule_id}/diff:
    get:
      tags:
      - v1:authz:permission:versioning
      summary: Diff Versions
      description: Returns the JSON-patch diff between two versions of a permission rule.
      operationId: diff_versions_api_v1_authz_permission__rule_id__diff_get
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      - name: from
        in: query
        required: true
        schema:
          type: integer
          title: From
      - name: to
        in: query
        required: true
        schema:
          type: integer
          title: To
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DiffOperation'
                title: Response Diff Versions Api V1 Authz Permission  Rule Id  Diff Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{rule_id}/drafts:
    post:
      tags:
      - v1:authz:permission:versioning
      summary: Create Draft
      description: Creates a new draft version of a permission rule, optionally seeded from an existing version or snapshot.
      operationId: create_draft_api_v1_authz_permission__rule_id__drafts_post
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDraftRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{rule_id}/drafts/{version}:
    put:
      tags:
      - v1:authz:permission:versioning
      summary: Update Draft
      description: Replaces the snapshot of an existing draft version of a permission rule.
      operationId: update_draft_api_v1_authz_permission__rule_id__drafts__version__put
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDraftRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - v1:authz:permission:versioning
      summary: Discard Draft
      description: Discards a draft version of a permission rule.
      operationId: discard_draft_api_v1_authz_permission__rule_id__drafts__version__delete
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{rule_id}/drafts/{version}/freeze:
    post:
      tags:
      - v1:authz:permission:versioning
      summary: Freeze Draft
      description: Freezes a draft version of a permission rule, making it immutable.
      operationId: freeze_draft_api_v1_authz_permission__rule_id__drafts__version__freeze_post
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{rule_id}/publish:
    post:
      tags:
      - v1:authz:permission:versioning
      summary: Publish
      description: Publishes a version of a permission rule, materializing its snapshot into the live rule.
      operationId: publish_api_v1_authz_permission__rule_id__publish_post
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          title: Rule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateDraftRequest:
      properties:
        from_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: From Version
        permission:
          anyOf:
          - $ref: '#/components/schemas/PermissionDraftRequest'
          - type: 'null'
      type: object
      title: CreateDraftRequest
      description: 'Seed a draft from an existing version (`from_version`) and/or from a proposed

        permission rule (`permission`).


        A draft is a full proposed permission rule, described with the same high-level

        fields as the create API — the caller never supplies a raw rule-record body. The

        router renders it through the permission template (scope-validated) before storing,

        so a draft can only ever be a canonical, in-scope rule.'
    UpdateDraftRequest:
      properties:
        permission:
          $ref: '#/components/schemas/PermissionDraftRequest'
      type: object
      required:
      - permission
      title: UpdateDraftRequest
      description: 'Replace a draft''s contents with a proposed permission rule (high-level fields,

        same as the create API — never a raw rule-record body).'
    VersionNode:
      properties:
        version:
          type: integer
          title: Version
        parent_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parent Version
        is_base:
          type: boolean
          title: Is Base
          default: false
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
      type: object
      required:
      - version
      title: VersionNode
    PublishRequest:
      properties:
        target_version:
          type: integer
          title: Target Version
        allow_branch_switch:
          type: boolean
          title: Allow Branch Switch
          default: false
      type: object
      required:
      - target_version
      title: PublishRequest
    PermissionDraftRequest:
      properties:
        subject_id:
          type: string
          title: Subject Id
          description: Subject identifier (user, group, or role).
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: Project the rule applies to. Provide this OR workspace_id.
        workspace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Id
          description: Workspace the rule applies to. Provide this OR project_id.
        workspace_scope:
          type: boolean
          title: Workspace Scope
          description: If true (and workspace_id is set), the rule only applies at the workspace scope, not to projects within it.
          default: false
        mode:
          allOf:
          - $ref: '#/components/schemas/PermissionMode'
          description: Whether the listed permissions are allowed or denied.
        permissions:
          items:
            $ref: '#/components/schemas/Permission'
          type: array
          minItems: 1
          title: Permissions
          description: The (resource, action) pairs to toggle.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Optional human-readable name.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional human-readable description.
      type: object
      required:
      - subject_id
      - mode
      - permissions
      title: PermissionDraftRequest
      description: 'A proposed permission rule for a draft version.


        Same identifying fields and full validation as create, but without lifecycle

        fields (enabled/expires_at/debug_for): publishing a draft materializes only the

        rule body, never the lifecycle columns, so a draft cannot carry them.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Permission:
      properties:
        resource:
          type: string
          title: Resource
          description: Resource identifier (e.g. 'compute:server')
        action:
          type: string
          title: Action
          description: Action identifier (e.g. 'create')
      type: object
      required:
      - resource
      - action
      title: Permission
    DiffOperation:
      properties:
        op:
          type: string
          title: Op
        path:
          type: string
          title: Path
        value:
          title: Value
        from:
          anyOf:
          - type: string
          - type: 'null'
          title: From
      type: object
      required:
      - op
      - path
      title: DiffOperation
    PermissionMode:
      type: string
      enum:
      - allow
      - deny
      title: PermissionMode
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    SwaggerLogin:
      type: oauth2
      flows:
        password:
          tokenUrl: /api/v1/account/login_swagger
          scopes: {}
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API Key format -  base64('<id>:<secret>')