1. Docs
  2. API Reference
  3. List identities in Account

List identities in Account

GET/portal/v1/accounts/{accountSlug}/identities

Paginated listing of the Account's end-user identity directory, spanning every Environment in the Account rather than one App/Environment. Supports a free-text q search and filters for status, has_any_assignment, environment_id, and not_in_env (used by the add-from-directory picker to exclude identities already in a given Environment); sort accepts name, email, or created, defaulting to first_name ASC. Includes SSO/SCIM-provisioned, invited-but-unaccepted, and orphaned (zero-membership) identities.

Authentication

Bearer TokenAuthorization

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

Requires capability identities.viewIdentities

View end-user identities across the account. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.

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 term

max length 200

sort_bystring Optional

Column to sort by. Allowed values depend on the endpoint.

orderenum Optional

Sort direction

one of "asc" · "desc"

statusenum Optional

Filter by the Account-wide `is_active` flag. Omit to show all.

one of "active" · "inactive"

has_any_assignmentboolean Optional

When true, only identities with at least one role assignment somewhere in the Account. When false, only identities with zero assignments (the orphan filter — surfaces identities that exist in the directory but haven't been given access anywhere). Omit to show all.

not_in_envstring Optional

Exclude identities that already have an active EnvironmentMembership for the given Environment id. Drives the 'Add from directory' picker — the candidate list should only contain identities NOT already in the target Environment.

environment_idstring Optional

Filter the directory by Environment. Pass an Environment id to show only identities with an active membership there, or the literal `none` to show directory-only identities (no membership anywhere). Omit to show all.

Responses

application/json

  • itemsAccountIdentityRowDto[]*
  • paginationPageMetaDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on.

403account.capability_requiredForbidden
When it happens

The signed-in user's administrator roles do not grant the capability this endpoint requires.

Remediation

Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.

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–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

AccountIdentityRowDtoView all properties on this resource
Request
curl -X GET "https://auth.canopy-io.com/portal/v1/accounts/{accountSlug}/identities?page=0&take=0&q=value&sort_by=value&order=asc&status=active&has_any_assignment=false&not_in_env=value&environment_id=value" \
  -H "Authorization: Bearer $CANOPY_TOKEN"
Response
{
  "items": [
    {
      "id": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "avatar_url": "string",
      "external_id": "string",
      "is_active": false,
      "email_verified": false,
      "environment_membership_count": 0,
      "total_assignments": 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
POSTCreate an Account identity
POSTBulk-create Account identities
GETGet directory counts for the Account
GETGet an Account identity
PATCHUpdate an Account identity profile
PATCHSet Account-wide is_active flag
POSTErase an identity (GDPR/CCPA right to be forgotten)
POSTAdmin-trigger a password reset email
POSTRe-send email verification
POSTRevoke all active sessions for an identity
GETList audit events for an Account identity
POSTAdd an identity to an Environment (create EnvironmentMembership)
POSTBulk-attach EnvironmentMemberships for the Add-from-directory picker
DELETERemove an identity from an Environment (revoke EnvironmentMembership)
 Was this page helpful?

Tell us how we can improve this guide.

Canopy