Permit.io Groups API

openapi: 3.1.0
info:
  title: Permit.io Access Requests (EAP) Access Requests (EAP) Groups API
  description: '

    Authorization as a service

    '
  version: 2.0.0
tags:
- name: Groups
paths:
  /v2/schema/{proj_id}/{env_id}/groups/direct:
    get:
      tags:
      - Groups
      summary: List Direct Group
      description: Paginated list of groups with various filters.
      operationId: list_direct_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: The tenant key or id to filter by
        required: false
        schema:
          type: string
          title: Tenant
          description: The tenant key or id to filter by
        name: tenant
        in: query
      - description: The resource key or id to filter by
        required: false
        schema:
          type: string
          title: Resource
          description: The resource key or id to filter by
        name: resource
        in: query
      - description: Page number of the results to fetch, starting at 1.
        required: false
        schema:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number of the results to fetch, starting at 1.
          default: 1
        name: page
        in: query
      - description: The number of results per page (max 100).
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Per Page
          description: The number of results per page (max 100).
          default: 30
        name: per_page
        in: query
      - description: Text search for the object name or key
        required: false
        schema:
          type: string
          title: Search
          description: Text search for the object name or key
        name: search
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResult_GroupReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/direct/{group_instance_key}:
    get:
      tags:
      - Groups
      summary: Get Direct Group
      description: Retrieve a specific group by its instance key.
      operationId: get_direct_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupReadSchema'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/children:
    get:
      tags:
      - Groups
      summary: List group children (EAP)
      description: List group children of a specific group.
      operationId: list_group_children
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      - description: Page number of the results to fetch, starting at 1.
        required: false
        schema:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number of the results to fetch, starting at 1.
          default: 1
        name: page
        in: query
      - description: The number of results per page (max 100).
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Per Page
          description: The number of results per page (max 100).
          default: 30
        name: per_page
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResult_GroupReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/parents:
    get:
      tags:
      - Groups
      summary: List group parents (EAP)
      description: List group parents of a specific group.
      operationId: list_group_parents
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      - description: Page number of the results to fetch, starting at 1.
        required: false
        schema:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number of the results to fetch, starting at 1.
          default: 1
        name: page
        in: query
      - description: The number of results per page (max 100).
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Per Page
          description: The number of results per page (max 100).
          default: 30
        name: per_page
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResult_GroupReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/users:
    get:
      tags:
      - Groups
      summary: List group users (EAP)
      description: Paginated list of all users in a group.
      operationId: list_group_users
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      - description: Page number of the results to fetch, starting at 1.
        required: false
        schema:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number of the results to fetch, starting at 1.
          default: 1
        name: page
        in: query
      - description: The number of results per page (max 100).
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Per Page
          description: The number of results per page (max 100).
          default: 30
        name: per_page
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResult_GroupUserReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/roles:
    get:
      tags:
      - Groups
      summary: List group roles (EAP)
      description: Paginated list of all roles assigned to a group.
      operationId: list_group_roles
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      - description: Page number of the results to fetch, starting at 1.
        required: false
        schema:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number of the results to fetch, starting at 1.
          default: 1
        name: page
        in: query
      - description: The number of results per page (max 100).
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Per Page
          description: The number of results per page (max 100).
          default: 30
        name: per_page
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResult_GroupRoleReadSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
    post:
      tags:
      - Groups
      summary: Assign Role To Group
      description: 'Assign a role to a group -

        It will create relation between the group and the resource, relationship between the resource instances and derivation from the member role to this role.'
      operationId: assign_role_to_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupAddRole'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
    delete:
      tags:
      - Groups
      summary: Remove Role From Group
      description: 'Remove a role from a group-

        It will remove the derivation from the member role to this role.'
      operationId: remove_role_from_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupAddRole'
        required: true
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}:
    get:
      tags:
      - Groups
      summary: Get Group
      description: Retrieve a specific group by its instance key.
      operationId: get_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - HTTPBearer: []
    delete:
      tags:
      - Groups
      summary: Delete Group
      description: Delete a group by its instance key.
      operationId: delete_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups:
    get:
      tags:
      - Groups
      summary: List Group
      description: List all groups.
      operationId: list_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: The tenant key or id to filter by
        required: false
        schema:
          type: string
          title: Tenant
          description: The tenant key or id to filter by
        name: tenant
        in: query
      - description: The resource key or id to filter by
        required: false
        schema:
          type: string
          title: Resource
          description: The resource key or id to filter by
        name: resource
        in: query
      - description: Include total count in response(will make the request slower)
        required: false
        deprecated: true
        schema:
          type: boolean
          title: Include Total Count
          description: Include total count in response(will make the request slower)
          default: false
        name: include_total_count
        in: query
      - description: Page number of the results to fetch, starting at 1.
        required: false
        schema:
          type: integer
          minimum: 1.0
          title: Page
          description: Page number of the results to fetch, starting at 1.
          default: 1
        name: page
        in: query
      - description: The number of results per page (max 100).
        required: false
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Per Page
          description: The number of results per page (max 100).
          default: 30
        name: per_page
        in: query
      - description: Text search for the object name or key
        required: false
        schema:
          type: string
          title: Search
          description: Text search for the object name or key
        name: search
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/GroupRead'
                type: array
                title: Response List Group V2 Schema  Proj Id   Env Id  Groups Get
                description: List of Groups
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - HTTPBearer: []
    post:
      tags:
      - Groups
      summary: Create Group
      description: Create a new group.
      operationId: create_group
      parameters:
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/users/{user_id}:
    put:
      tags:
      - Groups
      summary: Assign User To Group
      description: 'Assign a user to a group -

        This user will inherit the group''s roles.'
      operationId: assign_user_to_group
      parameters:
      - description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: User Id
          description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
        example: my_user
        name: user_id
        in: path
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: group_instance_key
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupAssignUser'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
    delete:
      tags:
      - Groups
      summary: Remove User From Group
      description: 'Remove a user from a group-

        This user will be removed from the member role of the group, and will no longer inherit the group''s roles.'
      operationId: remove_user_from_group
      parameters:
      - description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: User Id
          description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
        example: my_user
        name: user_id
        in: path
      - description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Proj Id
          description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
        example: my_project
        name: proj_id
        in: path
      - description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Env Id
          description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
        example: my_environment
        name: env_id
        in: path
      - description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        required: true
        schema:
          type: string
          title: Group Instance Key
          description: 'Either the unique id of the resource instance, or the URL-friendly key of the resource instance (i.e: the "slug").'
        example: my_instance_group
        name: gro

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/permit-io/refs/heads/main/openapi/permit-io-groups-api-openapi.yml