# Invitations

## Create

`client.organizations.invitations.create(stringorganizationID, InvitationCreateParamsparams, RequestOptionsoptions?): Invitation`

**post** `/organizations/{organization_id}/invitations`

Create an invitation to join an organization

### Parameters

- `organizationID: string`

  Organization ID or label identifier

- `params: InvitationCreateParams`

  - `email: string`

    Body param: Email address to invite

  - `role: OrganizationRole`

    Body param: Role to assign when invitation is accepted

    - `"org_admin"`

    - `"org_member"`

    - `"org_viewer"`

  - `xClientRequestID?: string`

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

### Returns

- `Invitation`

  - `id: string`

    Identifier for API resources. A 26-char nanoid (URL/DNS safe).

  - `created_at: string`

    The time the entity was created in utc

  - `created_by: string`

    ID of the user who created the invitation

  - `email: string`

    Email address for the invitation

  - `expires_at: string`

    When the invitation expires

  - `organization_id: string`

    Identifier for API resources. A 26-char nanoid (URL/DNS safe).

  - `role: OrganizationRole`

    Role that will be assigned when invitation is accepted

    - `"org_admin"`

    - `"org_member"`

    - `"org_viewer"`

  - `status: InvitationStatus`

    Status of an invitation

    - `"pending"`

    - `"accepted"`

    - `"expired"`

    - `"revoked"`

  - `updated_at: string`

    The time the entity was mostly recently updated in utc

  - `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.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const invitation = await client.organizations.invitations.create('x', {
  email: 'dev@stainless.com',
  role: 'org_admin',
});

console.log(invitation.id);
```

## List

`client.organizations.invitations.list(stringorganizationID, InvitationListParamsparams?, RequestOptionsoptions?): InvitationListResponse`

**get** `/organizations/{organization_id}/invitations`

List invitations for an organization

### Parameters

- `organizationID: string`

  Organization ID or label identifier

- `params: InvitationListParams`

  - `after?: string`

    Query param: Cursor for forward pagination

  - `before?: string`

    Query param: Cursor for backward pagination

  - `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.

    - `"permissions"`

    - `"total_count"`

  - `limit?: number`

    Query param: Maximum number of invitations to return

  - `xClientRequestID?: string`

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

### Returns

- `InvitationListResponse`

  - `items: Array<Invitation>`

    - `id: string`

      Identifier for API resources. A 26-char nanoid (URL/DNS safe).

    - `created_at: string`

      The time the entity was created in utc

    - `created_by: string`

      ID of the user who created the invitation

    - `email: string`

      Email address for the invitation

    - `expires_at: string`

      When the invitation expires

    - `organization_id: string`

      Identifier for API resources. A 26-char nanoid (URL/DNS safe).

    - `role: OrganizationRole`

      Role that will be assigned when invitation is accepted

      - `"org_admin"`

      - `"org_member"`

      - `"org_viewer"`

    - `status: InvitationStatus`

      Status of an invitation

      - `"pending"`

      - `"accepted"`

      - `"expired"`

      - `"revoked"`

    - `updated_at: string`

      The time the entity was mostly recently updated in utc

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

    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

    - `start_cursor?: string`

      Cursor pointing to the first item in the current page

  - `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.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const invitations = await client.organizations.invitations.list('x');

console.log(invitations.items);
```

## Delete

`client.organizations.invitations.delete(stringinvitationID, InvitationDeleteParamsparams, RequestOptionsoptions?): void`

**delete** `/organizations/{organization_id}/invitations/{invitation_id}`

Delete an invitation

### Parameters

- `invitationID: string`

  Identifier for API resources. A 26-char nanoid (URL/DNS safe).

- `params: InvitationDeleteParams`

  - `organization_id: string`

    Path param: Organization ID or label identifier

  - `xClientRequestID?: string`

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

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

await client.organizations.invitations.delete('ab3def8hij2klm9opq5rst7uvw', {
  organization_id: 'x',
});
```

## Domain Types

### Invitation

- `Invitation`

  - `id: string`

    Identifier for API resources. A 26-char nanoid (URL/DNS safe).

  - `created_at: string`

    The time the entity was created in utc

  - `created_by: string`

    ID of the user who created the invitation

  - `email: string`

    Email address for the invitation

  - `expires_at: string`

    When the invitation expires

  - `organization_id: string`

    Identifier for API resources. A 26-char nanoid (URL/DNS safe).

  - `role: OrganizationRole`

    Role that will be assigned when invitation is accepted

    - `"org_admin"`

    - `"org_member"`

    - `"org_viewer"`

  - `status: InvitationStatus`

    Status of an invitation

    - `"pending"`

    - `"accepted"`

    - `"expired"`

    - `"revoked"`

  - `updated_at: string`

    The time the entity was mostly recently updated in utc

  - `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.

### Invitation Status

- `InvitationStatus = "pending" | "accepted" | "expired" | "revoked"`

  Status of an invitation

  - `"pending"`

  - `"accepted"`

  - `"expired"`

  - `"revoked"`