NimbusNexus V1:authz:permission API

openapi: 3.2.0
info:
  title: NimbusNexus API — External V1:authz:permission API
  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
paths:
  /api/v1/authz/permission/:
    post:
      tags:
      - v1:authz:permission
      summary: Create Permission
      description: Creates a basic allow/deny permission rule for a subject within a project or workspace.
      operationId: create_permission_api_v1_authz_permission__post
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionRule'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                success: false
                message: Bad Request
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                success: false
                message: Unauthorized | Invalid token | Expired token | Authentication required
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                success: false
                message: Forbidden
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                success: false
                message: Not Found
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '409':
          description: Conflict
          content:
            application/json:
              example:
                success: false
                message: Conflict
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              example:
                code: 429
                message: Too many requests
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                success: false
                message: Internal Server Error
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - v1:authz:permission
      summary: Update Permission
      description: Updates an existing permission rule. Only `id` is required; every other field is partial — omitted content fields keep their existing value, and omitted lifecycle fields (enabled/expires_at/debug_for) leave the underlying columns untouched.
      operationId: update_permission_api_v1_authz_permission__patch
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionRule'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                success: false
                message: Bad Request
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                success: false
                message: Forbidden
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                success: false
                message: Not Found
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              example:
                code: 429
                message: Too many requests
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                success: false
                message: Internal Server Error
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - v1:authz:permission
      summary: Get Permission
      description: Retrieves a single permission rule by its identifier.
      operationId: get_permission_api_v1_authz_permission__get
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: rule_id
        in: query
        required: true
        schema:
          type: string
          title: Rule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionRule'
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                success: false
                message: Forbidden
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              example:
                code: 429
                message: Too many requests
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                success: false
                message: Internal Server Error
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/{permission_id}:
    delete:
      tags:
      - v1:authz:permission
      summary: Delete Permission
      description: Deletes a permission rule. Only rules created via this API and visible to the caller can be deleted.
      operationId: delete_permission_api_v1_authz_permission__permission_id__delete
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
      parameters:
      - name: permission_id
        in: path
        required: true
        schema:
          type: string
          title: Permission Id
      - name: ignore_missing
        in: query
        required: false
        schema:
          type: boolean
          description: If true, succeed silently when the rule does not exist
          default: false
          title: Ignore Missing
        description: If true, succeed silently when the rule does not exist
      responses:
        '204':
          description: Successful Response
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                success: false
                message: Forbidden
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                success: false
                message: Not Found
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              example:
                code: 429
                message: Too many requests
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                success: false
                message: Internal Server Error
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/authz/permission/search:
    post:
      tags:
      - v1:authz:permission
      summary: Search Permissions
      description: Lists permission rules created via this API, filtered by the provided criteria and the caller's scope.
      operationId: search_permissions_api_v1_authz_permission_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PermissionRule'
                type: array
                title: Response Search Permissions Api V1 Authz Permission Search Post
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Unauthorized | Invalid token | Expired token | Authentication required
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Forbidden
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                code: 429
                message: Too many requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Internal Server Error
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
components:
  schemas:
    PermissionRule:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the underlying rule
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Human-readable name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Human-readable description
        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
        workspace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Id
          description: Workspace the rule applies to
        workspace_scope:
          type: boolean
          title: Workspace Scope
          description: If true, the rule only applies at workspace scope and not to projects within the workspace
          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
          title: Permissions
          description: The (resource, action) pairs toggled by this rule
        enabled:
          type: boolean
          title: Enabled
          description: Manual on/off switch. When False, the rule is excluded from evaluation.
          default: true
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: UTC cutoff after which the rule auto-deactivates. Null means no expiry.
        debug_for:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Debug For
          description: Subject ids (users/groups/roles) for which this rule participates only when the authorize request carries debug=True. Null means a live rule.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: Timestamp when the rule was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: Timestamp when the rule was last updated
      type: object
      required:
      - id
      - subject_id
      - mode
      - permissions
      title: PermissionRule
    PermissionUpdateRequest:
      properties:
        subject_id:
          anyOf:
          - type: string
          - type: 'null'
          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:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Workspace Scope
          description: If true (and workspace_id is set), the rule only applies at the workspace scope, not to projects within it.
        mode:
          anyOf:
          - $ref: '#/components/schemas/PermissionMode'
          - type: 'null'
          description: Whether the listed permissions are allowed or denied.
        permissions:
          anyOf:
          - items:
              $ref: '#/components/schemas/Permission'
            type: array
          - type: 'null'
          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.
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
          description: Manual on/off switch. When False, the rule is excluded from evaluation. Defaults to True on create; leave unset on update to leave the existing value untouched.
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: UTC cutoff after which the rule auto-deactivates. Null means no expiry.
        debug_for:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Debug For
          description: Subject ids for which this rule participates only when the authorize request carries debug=True. Requires expires_at to be set.
        id:
          type: string
          title: Id
          description: Identifier of the permission rule to update
      type: object
      required:
      - id
      title: PermissionUpdateRequest
      description: 'Partial update. Only `id` is required; every other field is optional.


        Fields the caller omits are left unchanged on the existing rule (the router

        merges the request with the existing rule''s state before re-rendering the

        rule body). Cross-field invariants that depend on existing state are

        enforced **only** when the caller''s request would violate them by itself —

        e.g. you cannot clear both `project_id` and `workspace_id` in the same

        request (which would leave the rule with no scope).'
    PermissionCreateRequest:
      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.
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
          description: Manual on/off switch. When False, the rule is excluded from evaluation. Defaults to True on create; leave unset on update to leave the existing value untouched.
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: UTC cutoff after which the rule auto-deactivates. Null means no expiry.
        debug_for:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Debug For
          description: Subject ids for which this rule participates only when the authorize request carries debug=True. Requires expires_at to be set.
      type: object
      required:
      - subject_id
      - mode
      - permissions
      title: PermissionCreateRequest
      description: Create requires the canonical set of identifying fields. Validators here run against the full request because there is no existing state to merge with.
    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
    ResponseBaseErrorOut:
      properties:
        success:
          type: boolean
          title: Success
          default: false
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: ResponseBaseErrorOut
    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
    PermissionSearchRequest:
      properties:
        subject_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Subject Ids
          description: Restrict to rules for these subjects
        mode:
          anyOf:
          - $ref: '#/components/schemas/PermissionMode'
          - type: 'null'
          description: Restrict to allow or deny rules
        project_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Project Id
          description: Restrict to rules scoped to this project
        workspace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Id
          description: Restrict to rules scoped to this workspace
      type: object
      title: PermissionSearchRequest
    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>')