---
title: "List Scope Groups"
method: GET
path: "/api/v2/scope-groups"
tags: ["Scope Groups"]
---

# List Scope Groups

`GET /api/v2/scope-groups`

## Request

- Base URL: `https://console.jumpcloud.com`
- URL: `https://console.jumpcloud.com/api/v2/scope-groups`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/docs/api/v2/scope-groups/get.ts> (a function with typed inputs; its response is checked against the schema)

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}'
```

## Query parameters

- `limit` integer
- `skip` integer
- `filter` string[]
- `sort` string[]

## Headers

- `x-total-count` integer
- `x-org-id` string
- `x-provider-id` string

## Response `200`

OK

- object
  - `totalCount` integer, required: Total count of scope groups matching the filter criteria
  - `results` ScopeGroup[], required
    - `id` string: Unique identifier for the scope group
    - `groupName` string: Name of the scope group
    - `groupKey` string: A unique, URL-friendly key for the scope group.
    - `fullAccessScopes` string[]: List of scopes that grant full access to the group.
    - `displayToUsers` boolean: Whether this scope group should be displayed to users
    - `groupDescription` string: Description of the scope group's purpose
    - `scopes` Scope[]: List of scopes within this group
      - `key` string: Unique key for the scope
      - `label` string: Human-readable label for the scope
      - `subgroupLabel` string: A common label for a group of related scopes.
      - `displayToUsers` boolean: Whether this scope should be displayed to users
      - `description` string: Description of what this scope controls
      - `permissionType` 'granular' | 'access_level' | 'actions': The type of permission structure for UI rendering.
      - `allowsNoAccess` boolean: Whether No Access option available for the scope. It would be applicable when permission_type:access_level
      - `permissions` object[]: Available permission levels for this scope
        - `key` string: Permission level key (e.g. fullAccess, view, create, update, delete, allow)
        - `values` string[]: Scope strings granted at this permission level
    - `createdAt` string, date-time: When the scope group was created
    - `updatedAt` string, date-time: When the scope group was last updated

## Other responses

- `400`: Bad Request
- `401`: Unauthenticated
- `403`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error

---

[API](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api.md) - [All operations](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jumpcloud/apis/jumpcloud-console-api/revisions/f396d9271b46?raw)