--- title: "List Identities for a Realm" method: GET path: "/v1/tenants/{tenant_id}/realms/{realm_id}/identities" tags: ["Identities"] --- # List Identities for a Realm `GET /v1/tenants/{tenant_id}/realms/{realm_id}/identities` ## Request - Base URL: `https://api-us.beyondidentity.com` - URL: `https://api-us.beyondidentity.com/v1/tenants/{tenant_id}/realms/{realm_id}/identities` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) To list identities for a realm, send a GET request to `/v1/tenants/$TENANT_ID/realms/$REALM_ID/identities`. The response will only contain identities matching the filter in the request. If no filter is provided, the request will match all identities in the realm. Currently, the only supported filter is `traits.username eq "$USERNAME"`. The response will contain at most 200 items and may contain a page token to query the remaining items. If page size is not specified, the response will contain 20 items. There is no defined ordering of the list of identities in the response. Note that the maximum and default page sizes are subject to change. When paginating, the page size is maintained by the page token but may be overridden on subsequent requests. The filter is also maintained by the page token but it may not be overridden. If specified, the request filter must match the filter maintained by the page token, otherwise you will receive a 400 error. The skip is not maintained by the page token and must be specified on each subsequent request. Page tokens expire after one week. Requests which specify an expired page token will result in undefined behavior. ## Path parameters - `tenant_id` string, required - `realm_id` string, required ## Query parameters - `filter` string - `page_size` integer - `page_token` string - `skip` integer ## Response `200` The response will be a JSON object with keys for `identities` and `total_size`. `identities` will be set to an array of identity objects, each of which contains the standard identity attributes. `total_size` will be set to the total number of items matched by the list request. If there are more items to be returned by the requested query, the response will also contain a key called `next_page_token`. - ListIdentitiesResponse: Response for ListIdentities. - `identities` Identity[], required: An unordered array of identities corresponding to the request. - `id` string: A unique identifier for the identity. This is automatically generated on creation. This field is immutable and read-only. This field is unique within the realm. - `realm_id` string: A unique identifier for the identity's realm. This is automatically set on creation. This field is immutable and read-only. - `tenant_id` string: A unique identifier for the identity's tenant. This is automatically set on creation. This field is immutable and read-only. - `display_name` string: A human-readable name for the identity. This name is used for display purposes. - `create_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the identity was created. This is automatically generated on creation. This field is read-only. - `update_time` string, date-time: A time value given in ISO8601 combined date and time format that represents when the identity was last updated. This is automatically updated when the identity is updated. This field is read-only. - `status` string: Indicator for the identity's administrative status. If 'active', the identity is able to generate passkeys and login. If 'suspended', the identity is unable to generate passkeys or login. - `traits` TraitsV0: Set of traits associated with an identity. - `type` string, required: The type of the traits schema. This value must be provided on all writes. - `username` string: A required, unique, case-insensitive username for an identity in the realm. - `primary_email_address` string: Email address serving as primary contact for identity. - `secondary_email_address` string: An additional email address for the user. - `external_id` string: An ID issued by the provisioning client. It is assumed that the value's uniqueness is controlled by the client setting the value. - `family_name` string: The family name or last name in most Western languages. - `given_name` string: The given name or first name in most Western languages. - `formatted_name` string: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. "Ms. Barbara Jane Jensen, III"). - `middle_name` string: The middle name of the user, if applicable. - `honorific_prefix` string: Honorifics like "Mr.", "Mrs.", "Dr.", etc. - `honorific_suffix` string: Suffixes such as "Jr.", "Sr.", "III", etc. - `nick_name` string: A nickname the user goes by. - `title` string: The user's job title. - `primary_phone` string: The primary contact phone number for the user. - `secondary_phone` string: An additional phone number for the user. - `profile_url` string: A URL to the user's profile. - `photo` string: A URL to the user's photo. - `preferred_language` string: The user's preferred language. - `locale` string: The locale of the user, typically in the format of language-region. - `timezone` string: The timezone of the user. - `formatted_address` string: The full mailing address, formatted for display or use with a mailing label. This attribute MAY contain newlines. - `street_address` string: The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute MAY contain newlines. - `locality` string: The locality or city of the user. - `region` string: The region or state of the user. - `postal_code` string: The zip code or postal code of the user. - `country` string: The country of the user. - `user_type` string: Used to identify the relationship between the organization and the user. Typical values used might be 'Contractor', 'Employee', 'Intern', 'Temp', 'External', and 'Unknown', but any value may be used. - `employee_number` string: The employee number assigned to the user, typically based on order of hire or association with an organization. - `cost_center` string: The cost center associated with the user. - `organization` string: The organization the user belongs to. - `division` string: The division of the organization the user belongs to. - `department` string: The department of the organization the user belongs to. - `manager_id` string: The unique identifier for the user's manager. - `manager_name` string: The name of the user's manager. - `enrollment_status` 'ENROLLED' | 'PENDING' | 'INVITE_FAILED' | 'UNENROLLED': Indicator for the identity's enrollment status. If 'ENROLLED', the identity has 1 or more active passkeys. If 'PENDING', the identity has no active passkeys and 1 or more pending enrollments. If 'INVITE_FAILED', the identity has no active passkeys, no pending enrollments, and 1 or more failed enrollments. If 'UNENROLLED', the identity is not enrolled in the organization. May be undefined. This field is output-only. - `total_size` integer, required: Total number of results returned by the operation. This value may be larger than the number of resources returned, such as when returning a single page where multiple pages are available. - `next_page_token` string: Token used to fetch the next set of results. If this field is omitted, there are no subsequent pages. ## Other responses - `400`: Bad request. - `401`: Unauthorized. - `403`: Forbidden. - `404`: The resource was not found. - `500`: Server error. ## Changes - **2026-11-06** `42f3cac49392`: 1 info - added the optional property `identities/items/enrollment_status` to the response with the `200` status [Operation history](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/changes/v1/tenants/:tenant_id/realms/:realm_id/identities/get.md) --- [API](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api.md) - [All operations](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/llms.txt) - [OpenAPI document](https://skmtc.dev/beyondidentity/apis/beyond-identity-secure-access-api/revisions/42f3cac49392?raw)