Frontegg User Groups API

openapi: 3.2.0
info:
  title: Entitlements Agent (PDP) User Groups API
  description: 'The endpoints in this section pertain to the usage of an Entitlements Agent. When your application or service needs to verify entitlements, it can query the Entitlements Agent directly via HTTP.


    These endpoints can be integrated into any backend framework, enabling you to leverage entitlements for advanced authorization needs.'
  version: '1.0'
tags:
- name: User Groups
  x-displayName: User groups
paths:
  /resources/groups/v1:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    get:
      operationId: GroupsControllerV1_getAllGroups
      summary: Get All Groups
      description: Retrieve all user groups for an account (tenant).
      parameters:
      - name: _groupsRelations
        required: false
        in: query
        schema:
          enum:
          - roles
          - users
          - rolesAndUsers
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupsResponse'
      tags:
      - User Groups
      security:
      - bearer: []
    post:
      operationId: GroupsControllerV1_createGroup
      summary: Create Group
      description: 'Create a user group for an account (tenant).


        Provide the group details in the request body.'
      parameters:
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
      tags:
      - User Groups
      security:
      - bearer: []
  /resources/groups/v1/bulkGet:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: GroupsControllerV1_getGroupsByIds
      summary: Get Groups by Ids
      description: 'Retrieve user groups by given IDs for an account (tenant).


        Provide the group IDs in the request body.'
      parameters:
      - name: _groupsRelations
        required: false
        in: query
        schema:
          enum:
          - roles
          - users
          - rolesAndUsers
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetGroupsDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupsResponse'
      tags:
      - User Groups
      security:
      - bearer: []
  /resources/groups/v1/{id}:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    patch:
      operationId: GroupsControllerV1_updateGroup
      summary: Update Group
      description: 'Update a user group by ID for an account (tenant).


        Provide the group ID as a path parameter and the updated group details in the request body.'
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
      tags:
      - User Groups
      security:
      - bearer: []
    delete:
      operationId: GroupsControllerV1_deleteGroup
      summary: Delete Group
      description: 'Delete a user group by ID for an account (tenant).


        Provide the group ID as a path parameter.'
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - User Groups
      security:
      - bearer: []
    get:
      operationId: GroupsControllerV1_getGroupById
      summary: Get Group by ID
      description: 'Retrieve a user group by ID for an account (tenant).


        Provide the group ID as a path parameter.'
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: _groupsRelations
        required: false
        in: query
        schema:
          enum:
          - roles
          - users
          - rolesAndUsers
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
      tags:
      - User Groups
      security:
      - bearer: []
  /resources/groups/v1/config:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    get:
      operationId: GroupsControllerV1_getGroupsConfiguration
      summary: Get Groups Configuration
      description: Retrieve the user group configuration for your environment.
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGroupConfigurationResponse'
      tags:
      - User Groups
      security:
      - bearer: []
    post:
      operationId: GroupsControllerV1_createOrUpdateGroupsConfiguration
      summary: Create or Update Groups Configuration
      description: 'Create or update the user group configuration for your environment.


        Provide the configuration details in the request body.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateGroupConfigurationDto'
      responses:
        '201':
          description: ''
      tags:
      - User Groups
      security:
      - bearer: []
  /resources/groups/v1/{groupId}/roles:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: GroupsControllerV1_addRolesToGroup
      summary: Add Roles to Group
      description: 'Add roles to an existing user group.


        A user can assign only roles that are lower than their own.'
      parameters:
      - name: groupId
        required: true
        in: path
        schema:
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRolesOnGroupDto'
      responses:
        '201':
          description: ''
      tags:
      - User Groups
      security:
      - bearer: []
    delete:
      operationId: GroupsControllerV1_removeRolesFromGroup
      summary: Remove Roles From Group
      description: 'Remove roles from an existing user group.


        Provide the roles to remove in the request body.'
      parameters:
      - name: groupId
        required: true
        in: path
        schema:
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRolesOnGroupDto'
      responses:
        '200':
          description: ''
      tags:
      - User Groups
      security:
      - bearer: []
  /resources/groups/v1/{groupId}/users:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    post:
      operationId: GroupsControllerV1_addUsersToGroup
      summary: Add Users to Group
      description: 'Add users to an existing user group.


        Only users with higher roles than the group''s roles are allowed to perform this action.'
      parameters:
      - name: groupId
        required: true
        in: path
        schema:
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUsersOnGroupDto'
      responses:
        '201':
          description: ''
      tags:
      - User Groups
      security:
      - bearer: []
    delete:
      operationId: GroupsControllerV1_removeUsersFromGroup
      summary: Remove Users From Group
      description: 'Remove users from an existing user group.


        Provide the users to remove in the request body.'
      parameters:
      - name: groupId
        required: true
        in: path
        schema:
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUsersOnGroupDto'
      responses:
        '200':
          description: ''
      tags:
      - User Groups
      security:
      - bearer: []
  /resources/groups/v2:
    servers:
    - url: https://api.frontegg.com/identity
      description: EU Region
    - url: https://api.us.frontegg.com/identity
      description: US Region
    - url: https://api.ca.frontegg.com/identity
      description: CA Region
    - url: https://api.au.frontegg.com/identity
      description: AU Region
    - url: https://{domain}.frontegg.com/identity
      description: Frontegg sub-domain for use with user tokens
      variables:
        domain:
          default: app-xxx
    get:
      operationId: GroupsControllerV2_getAllGroupsPaginated
      summary: Get All Groups Paginated
      description: 'Retrieve all user groups for an account (tenant), with pagination.


        Use query parameters to control pagination and optionally include related group data.'
      parameters:
      - name: _groupsRelations
        required: false
        in: query
        schema:
          enum:
          - roles
          - users
          - rolesAndUsers
          type: string
      - name: _limit
        required: false
        in: query
        schema:
          minimum: 1
          type: number
      - name: _offset
        required: false
        in: query
        schema:
          minimum: 0
          type: number
        description: The page number to retrieve. For example, use 0 for the first page, 1 for the second page.
      - name: _sortBy
        required: false
        in: query
        schema:
          enum:
          - id
          - name
          - createdAt
          - updatedAt
          type: string
      - name: _order
        required: false
        in: query
        schema:
          enum:
          - ASC
          - DESC
          type: string
      - name: frontegg-tenant-id
        in: header
        description: The tenant identifier. Required for requests to api.frontegg.com (or your region) when using a management token. Parsed from the token when using user or API tokens
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/FronteggPaginationWrapper'
                - properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/GroupResponse'
                    _links:
                      $ref: '#/components/schemas/FronteggPaginationLinks'
                    _metadata:
                      $ref: '#/components/schemas/FronteggPaginationMetadata'
      tags:
      - User Groups
      security:
      - bearer: []
components:
  schemas:
    FronteggPaginationMetadata:
      type: object
      properties:
        totalItems:
          type: number
        totalPages:
          type: number
      required:
      - totalItems
      - totalPages
    CreateOrUpdateGroupConfigurationDto:
      type: object
      properties:
        enabled:
          type: boolean
          description: Determine whether groups are enabled/disabled. Default value is true.
          default: true
        rolesEnabled:
          type: boolean
          description: Determine whether groups can have roles or not. Default value is true.
          default: true
    GetGroupConfigurationResponse:
      type: object
      properties:
        enabled:
          type: boolean
        rolesEnabled:
          type: boolean
      required:
      - enabled
      - rolesEnabled
    UpdateGroupDto:
      type: object
      properties:
        color:
          type: string
          description: Color for group display
        description:
          type: string
          description: Group description
        metadata:
          type: string
          description: Stringified JSON object
          example: '{}'
        name:
          type: string
          description: Group unique name
    CreateGroupDto:
      type: object
      properties:
        color:
          type: string
          description: Color for group display
        description:
          type: string
          description: Group description
        metadata:
          type: string
          description: Stringified JSON object
          example: '{}'
        name:
          type: string
          description: Group unique name
      required:
      - name
    FronteggPaginationLinks:
      type: object
      properties:
        next:
          type: string
        prev:
          type: string
        first:
          type: string
        last:
          type: string
      required:
      - next
      - prev
      - first
      - last
    UpdateRolesOnGroupDto:
      type: object
      properties:
        roleIds:
          description: Will add / remove requested roles from the group
          example:
          - 5fbae0d3-a3b7-4b1e-8d64-6c9428f84aae
          - 8b2d0f9a-f39e-49b3-98ca-93c85c06d1a7
          type: array
          items:
            type: string
      required:
      - roleIds
    GroupUserDto:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        profilePictureUrl:
          type: string
        createdAt:
          format: date-time
          type: string
        activatedForTenant:
          type: boolean
      required:
      - id
      - email
      - name
      - profilePictureUrl
      - createdAt
      - activatedForTenant
    RoleDto:
      type: object
      properties:
        id:
          type: string
        vendorId:
          type: string
        tenantId:
          type: string
        key:
          type: string
        name:
          type: string
        description:
          type: string
        isDefault:
          type: boolean
        firstUserRole:
          type: boolean
        level:
          type: number
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - vendorId
      - tenantId
      - key
      - name
      - description
      - isDefault
      - firstUserRole
      - level
      - createdAt
      - updatedAt
    FronteggPaginationWrapper:
      type: object
      properties: {}
    UpdateUsersOnGroupDto:
      type: object
      properties:
        userIds:
          description: An array of User IDs to add / remove existing users to / from the group.
          example:
          - 262io276-3c5v-9y31-ba03-281674a89d4c
          - eeooc819-87dd-1cdd-b81d-e8829vm9d684
          type: array
          items:
            type: string
      required:
      - userIds
    GroupResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        color:
          type: string
        description:
          type: string
        metadata:
          type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/RoleDto'
        users:
          type: array
          items:
            $ref: '#/components/schemas/GroupUserDto'
        managedBy:
          enum:
          - frontegg
          - scim2
          type: string
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - name
      - color
      - description
      - metadata
      - roles
      - users
      - managedBy
      - createdAt
      - updatedAt
    GroupsResponse:
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/GroupResponse'
      required:
      - groups
    GetGroupsDto:
      type: object
      properties:
        groupsIds:
          description: Group IDs
          type: array
          items:
            type: string
      required:
      - groupsIds
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
x-tagGroups:
- name: Entitlements Agent (PDP)
  tags:
  - Entitlements Check
- name: Audits Overview
  tags:
  - Main
  - Metrics
- name: Entitlements Overview
  tags:
  - Plans
  - API Access Control
  - API Access Control Configurations
  - Features
  - Entitlements
  - Feature Flags
  - ReBAC
- name: Authentication and Identity Management
  tags:
  - API token
  - API tokens
  - Account invitations
  - Account invitations settings
  - Account roles
  - Approval Flows
  - Core settings
  - Custom social OAuth provider
  - Data migration
  - Delegation
  - Domain restrictions
  - Email configuration
  - Email templates
  - General
  - IP restrictions
  - Lockout policy
  - M2M tokens
  - MFA
  - MFA configuration
  - MFA settings
  - Password settings
  - Passwordless
  - Permissions
  - Permissions categories
  - Personal tokens
  - Roles
  - SMS
  - SMS configuration
  - SMS templates
  - Sessions configuration
  - Sessions management
  - User emails policy
  - User groups
  - User management
  - Users
  - User pools
  - User sessions
  - Users-applications management
- name: SCIM Provisioning Overview
  tags:
  - SCIM settings
  - SCIM configurations
- name: Single Sign-On Overview
  tags:
  - SAML configurations
  - SSO settings
  - SSO configurations
  - OIDC configurations
- name: Account Management Overview
  tags:
  - Accounts
  - tenants_other
  - Sub-accounts
  - Account settings
  - Account migration
  - Sub-accounts and hierarchy