Organizations

List Identities

client.organizations.listIdentities(, ?, ?): OrganizationListIdentitiesResponse { items, page_info, pagination, permissions }

GET/organizations/{organization_id}/identities

List unified view of users and invitations in an organization

ParametersExpand Collapse

organizationID: string

Organization ID or label identifier

minLength1

maxLength255

params: OrganizationListIdentitiesParams { after, before, expand, 4 more }

after?: string

Query param: Cursor for forward pagination

minLength1

maxLength255

before?: string

Query param: Cursor for backward pagination

minLength1

maxLength255

expand?: Array<"permissions" | "total_count">

Query param: Fields to expand in the response. Supports "permissions" to include the permissions field with the caller's permissions for the resource. For list organization identities only, "total_count" populates pagination.total_count with the number of identities matching the same filters as the list (excluding cursor and limit). Other operations ignore expand values they do not use.

Accepts one of the following:

"permissions"

"total_count"

limit?: number

Query param: Maximum number of identities to return

minimum1

maximum100

queryEmail?: string

Query param: Search identities by email substring (case-insensitive)

minLength1

maxLength255

role?: OrganizationRole

Query param: Filter identities by role

Accepts one of the following:

"org_admin"

"org_member"

"org_viewer"

xClientRequestID?: string

Header param: Unique request identifier specified by the originating caller and passed along by proxies.

formatuuid

ReturnsExpand Collapse

OrganizationListIdentitiesResponse { items, page_info, pagination, permissions }

List of identities (users and invitations) in an organization

items: Array<Item>

id: string

The identity ID (user or invitation)

minLength1

maxLength255

created_at: string

The time the entity was created in utc

formatdate-time

email: string

Email address of the identity

formatemail

role: OrganizationRole

Role in the organization

Accepts one of the following:

"org_admin"

"org_member"

"org_viewer"

source: string

Identity provider issuer

formaturi

status: "active" | "disabled" | "pending" | 3 more

Status of the identity (OrganizationStatus for users, InvitationStatus for invitations)

Accepts one of the following:

"active"

"disabled"

"pending"

"accepted"

"expired"

"revoked"

type: "user" | "invitation"

Type of identity (user or invitation)

Accepts one of the following:

"user"

"invitation"

updated_at: string

The time the entity was mostly recently updated in utc

formatdate-time

permissions?: Record<string, Record<string, boolean>>

Permissions granted to the authenticated principal for this resource. Only populated when the 'expand[]=permissions' query parameter is provided. Keys are resource types (e.g., "organizations"), values are objects mapping permission names to boolean values indicating if the permission is granted.

page_info: PageInfoCursor { has_next_page, has_prev_page, end_cursor, start_cursor }

Pagination information using cursor-based pagination

has_next_page: boolean

Whether there are more items after the current page

has_prev_page: boolean

Whether there are more items before the current page

end_cursor?: string

Cursor pointing to the last item in the current page

minLength1

maxLength255

start_cursor?: string

Cursor pointing to the first item in the current page

minLength1

maxLength255

pagination: Pagination { after_cursor, before_cursor, total_count }

Cursor-based pagination metadata returned alongside a list of results

after_cursor: string | null

An opaque cursor used for paginating through a list of results

minLength1

maxLength255

before_cursor: string | null

An opaque cursor used for paginating through a list of results

minLength1

maxLength255

total_count?: number

Total number of items across all pages. Only present when the request includes ?expand[]=total_count.

permissions?: Record<string, Record<string, boolean>>

List Identities

import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const response = await client.organizations.listIdentities('x');

console.log(response.items);

{
  "items": [
    {
      "id": "ab3def8hij2klm9opq5rst7uvw",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "role": "org_admin",
      "source": "https://example.com",
      "status": "active",
      "type": "user",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "permissions": {
        "organizations": {
          "read": true,
          "update": true
        },
        "users": {
          "read": true,
          "list": true
        }
      }
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_prev_page": true,
    "end_cursor": "x",
    "start_cursor": "x"
  },
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  },
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}

Returns Examples

{
  "items": [
    {
      "id": "ab3def8hij2klm9opq5rst7uvw",
      "created_at": "2019-12-27T18:11:19.117Z",
      "email": "dev@stainless.com",
      "role": "org_admin",
      "source": "https://example.com",
      "status": "active",
      "type": "user",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "permissions": {
        "organizations": {
          "read": true,
          "update": true
        },
        "users": {
          "read": true,
          "list": true
        }
      }
    }
  ],
  "page_info": {
    "has_next_page": true,
    "has_prev_page": true,
    "end_cursor": "x",
    "start_cursor": "x"
  },
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  },
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}