1. Docs
  2. API Reference
  3. List identities within the caller's operational scope

List identities within the caller's operational scope

GET/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/workspace/identities

The active members of the Environment that the caller administers, each with the roles they hold (roles, carrying assignment_id, node and effective dates). Requires workspace_identity.view somewhere in the Environment. An Environment-wide caller sees every member. A node-scoped caller sees only identities holding a role at a node in their subtree, and roles held in branches they cannot see are left off each row. Supports q, role_id (or the literal no_assignment), status, identity_id and sorting, and returns a paginated { items, pagination } sorted by first name by default.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Path Parameters

accountSlugstring Required

The Account's slug. An unknown one answers 404.

appSlugstring Required

The Application's slug within the Account.

envSlugstring Required

The Environment's slug within the Application.

Query Parameters

pagenumber Optional

Page number (1-based)

min 1

takenumber Optional

Items per page (1-100, default 20)

range 1–100

qstring Optional

Search names and emails

max length 200

sort_byenum Optional

Sort column. Defaults to `name`, A to Z.

one of "name" · "email" · "created"

orderenum Optional

Sort direction

one of "asc" · "desc"

role_idstring Optional

Filter to identities holding this role. Pass the literal `no_assignment` to return only members holding no role anywhere in the Environment.

identity_idstring Optional

Fetch one identity by id, through the same scoped query the list uses. Naming an identity outside the caller's branches returns nothing rather than reaching past the clamp.

statusenum Optional

Filter by whether the identity can sign in

one of "active" · "inactive"

Responses

application/json

  • itemsWorkspaceIdentityResponseDto[]*
  • paginationPageMetaDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Pagination

This endpoint returns a paginated collection. Use the query parameters below to page through results.

pagenumber

Page number (1-indexed). Defaults to 1.

takenumber

Items per page (1 to 100). Defaults to 20.

Each response includes an items array alongside a pagination object with item_count, page_count, has_previous_page, and has_next_page fields.

Returned object

WorkspaceIdentityResponseDtoView all properties on this resource
Request
curl -X GET "https://auth.canopy-io.com/portal/v1/accounts/value/applications/value/environments/value/workspace/identities?page=0&take=0&q=value&sort_by=name&order=asc&role_id=value&identity_id=value&status=active" \
  -H "Authorization: Bearer $CANOPY_TOKEN"
Response
{
  "items": [
    {
      "id": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "name": "string",
      "avatar_url": "string",
      "is_active": false,
      "roles": [
        {
          "assignment_id": "string",
          "id": "string",
          "name": "string",
          "node_id": "string",
          "node_name": "string",
          "effective_from": "string",
          "effective_to": "string",
          "version": 0
        }
      ],
      "created_at": "2026-04-20T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 0,
    "take": 0,
    "item_count": 0,
    "page_count": 0,
    "has_previous_page": false,
    "has_next_page": false
  }
}
 Related endpoints
GETResolve the caller's operational authority in the Environment
GETList an identity's responsibilities within the caller's scope
GETList the identity roles the caller may grant
GETList the hierarchy locations the caller may assign at
GETList the hierarchy nodes the caller can see in this Environment
GETList identity invitations within the caller's scope
POSTInvite an identity into a location with a role
GETList scoped operational activity within the caller's scope
GETDownload the scoped activity feed as CSV
GETHow long activity history is kept for this Account
POSTResend a scoped invitation
DELETERevoke a scoped invitation
POSTGrant an identity a role at a hierarchy node
PATCHMove or re-role an existing assignment
DELETERemove an identity's role assignment
 Was this page helpful?

Tell us how we can improve this guide.

Canopy