JUjumpcloud
Scope Groups

List Scope Groups

Retrieve scope groups for custom role creation.

Scope groups are global catalog resources.

Catalog visibility may depend on authenticated organization/provider context.

Direct/OU context can influence contextual catalog visibility.

Route availability is context-dependent: MSP provider-authoring requests (authenticated MSP provider without organization context) require SP-10009-custom-role-mtp. Organization contexts are always available.

When MSP Custom Roles is enabled, authenticated MSP provider context may request the provider-authoring catalog without x-org-id.

By default, returns scope groups with displayToUsers: true. Supports JumpCloud standard pagination, sorting, and basic filtering.

Response Format: Returns an object with totalCount and results array. The total count is also provided in the X-Total-Count response header.

Core Features

  • Global Resource: Same scope groups available to all organizations
  • Pagination: Standard limit and skip parameters
  • Sorting: Default sort by groupName (ascending), user-configurable
  • Filtering: displayToUsers:eq:true|false (defaults to true)

Sample Requests

# Default - displayToUsers: true, sorted by groupName
curl https://console.jumpcloud.com/api/v2/scope-groups \
  -H 'accept: application/json' \
  -H 'x-api-key: {API_KEY}'

# With pagination
curl 'https://console.jumpcloud.com/api/v2/scope-groups?limit=10&skip=20' \
  -H 'x-api-key: {API_KEY}'

# Custom sorting
curl 'https://console.jumpcloud.com/api/v2/scope-groups?sort[0][field]=groupName&sort[0][descending]=true' \
  -H 'x-api-key: {API_KEY}'

# Get internal scope groups (admin use)
curl 'https://console.jumpcloud.com/api/v2/scope-groups?filter=displayToUsers:eq:false' \
  -H 'x-api-key: {API_KEY}'
get/api/v2/scope-groups

Request

Query parameters

limitinteger

The number of records to return at once. Limited to 100.

skipinteger

The offset into the records to return.

filterstring[]

A filter to apply to the query.

Filter structure: <field>:<operator>:<value>.

field = Populate with a valid field from an endpoint response.

operator = Supported operators are: eq, ne, gt, ge, lt, le, between, search, in. Note: v1 operators differ from v2 operators.

value = Populate with the value you want to search for. Is case sensitive. Supports wild cards.

EX: GET /api/v2/groups?filter=name:eq:Test+Group

sortstring[]

The comma separated fields used to sort the collection. Default sort is ascending, prefix with - to sort descending.

Headers

x-total-countinteger
x-org-idstring

Organization identifier that can be obtained from console settings.

x-provider-idstring

Multi-tenant Provider identifier that can be obtained from console settings.

Response

OK

totalCountinteger required

Total count of scope groups matching the filter criteria

Example response

{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011",
      "groupName": "User Management",
      "groupKey": "user-management",
      "displayToUsers": true,
      "groupDescription": "Manage users",
      "scopes": [
        {
          "key": "users.unlock",
          "label": "Unlock user accounts",
          "subgroupLabel": "User Support",
          "displayToUsers": true,
          "description": "Unlock user accounts.",
          "permissionType": "actions",
          "permissions": [
            {
              "key": "allow",
              "values": [
                "users.unlock"
              ]
            }
          ]
        }
      ],
      "createdAt": "2023-07-23T12:00:00",
      "updatedAt": "2023-07-23T12:00:00"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.