openapi: 3.1.0
info:
  title: API Reference subpackage_bulkSync subpackage_permissions.subpackage_permissions/policies API
  version: 1.0.0
servers:
- url: https://app.polytomic.com
tags:
- name: subpackage_permissions.subpackage_permissions/policies
paths:
  /api/permissions/policies:
    get:
      operationId: list
      summary: List Policies
      description: 'Lists all policies in the caller''s organization.


        Each policy binds one or more roles to a set of resources, controlling what

        actions members with those roles can perform on those resources.


        To inspect a specific policy in detail, use

        [`GET /api/permissions/policies/{id}`](../../../api-reference/permissions/policies/get).'
      tags:
      - subpackage_permissions.subpackage_permissions/policies
      parameters:
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPoliciesResponseEnvelope'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    post:
      operationId: create
      summary: Create Policy
      description: 'Creates a new policy.


        A policy binds one or more roles to a set of resources, granting members who

        hold those roles the actions defined by them. Roles must already exist before

        they are referenced in a policy; create roles using

        [`POST /api/permissions/roles`](../../../api-reference/permissions/roles/create).'
      tags:
      - subpackage_permissions.subpackage_permissions/policies
      parameters:
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePolicyRequest'
  /api/permissions/policies/{id}:
    get:
      operationId: get
      summary: Get Policy
      description: 'Returns a single policy by ID, including all action/role bindings it defines.


        Returns the full set of action/role bindings defined by the policy, including

        the resources it applies to.'
      tags:
      - subpackage_permissions.subpackage_permissions/policies
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResponseEnvelope'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
    put:
      operationId: update
      summary: Update Policy
      description: 'Updates an existing policy.


        The update is a **full replacement** of the policy''s bindings. Any role or

        resource binding not included in the request body is removed. To make a

        partial change, fetch the current policy with

        [`GET /api/permissions/policies/{id}`](../../../../api-reference/permissions/policies/get), modify the relevant bindings,

        and send the complete object back.'
      tags:
      - subpackage_permissions.subpackage_permissions/policies
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyResponseEnvelope'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePolicyRequest'
    delete:
      operationId: delete
      summary: Delete Policy
      description: 'Deletes a policy.


        Deletion is permanent. Any access that was granted solely through this policy

        is revoked immediately for all users who depended on it.'
      tags:
      - subpackage_permissions.subpackage_permissions/policies
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer user API key
        required: true
        schema:
          type: string
      - name: X-Polytomic-Version
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    CreatePolicyRequest:
      type: object
      properties:
        name:
          type: string
        organization_id:
          type:
          - string
          - 'null'
          format: uuid
        policy_actions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PolicyAction'
      required:
      - name
      - policy_actions
      title: CreatePolicyRequest
    PolicyAction:
      type: object
      properties:
        action:
          type: string
        role_ids:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
      required:
      - action
      - role_ids
      title: PolicyAction
    UpdatePolicyRequest:
      type: object
      properties:
        name:
          type: string
        organization_id:
          type:
          - string
          - 'null'
          format: uuid
        policy_actions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PolicyAction'
      required:
      - name
      - policy_actions
      title: UpdatePolicyRequest
    PolicyResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        organization_id:
          type: string
          format: uuid
        policy_actions:
          type: array
          items:
            $ref: '#/components/schemas/PolicyAction'
        system:
          type: boolean
      title: PolicyResponse
    ApiError:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
        metadata:
          type: object
          additionalProperties:
            description: Any type
        status:
          type: integer
      title: ApiError
    PolicyResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PolicyResponse'
      title: PolicyResponseEnvelope
    ListPoliciesResponseEnvelope:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PolicyResponse'
      title: ListPoliciesResponseEnvelope
  securitySchemes:
    bearerUserAPIKey:
      type: http
      scheme: bearer
      description: Bearer user API key
    orgScopedAPIKey:
      type: http
      scheme: basic
      description: Basic organization-scoped API key
    bearerPartnerKey:
      type: http
      scheme: bearer
      description: Bearer partner API key