Skip to content
Docs
Invitations
Create

Create

API Reference
Organizations
Invitations

Create

client.organizations.invitations.create(stringorganizationID, InvitationCreateParams { email, role, xClientRequestID } params, RequestOptionsoptions?): Invitation { id, created_at, created_by, 7 more }
POST/organizations/{organization_id}/invitations

Create an invitation to join an organization

ParametersExpand Collapse
organizationID: string

Organization ID or label identifier

minLength1
maxLength255
params: InvitationCreateParams { email, role, xClientRequestID }
email: string

Body param: Email address to invite

formatemail
role: OrganizationRole

Body param: Role to assign when invitation is accepted

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
Invitation { id, created_at, created_by, 7 more }
id: string

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

minLength1
maxLength255
created_at: string

The time the entity was created in utc

formatdate-time
created_by: string

ID of the user who created the invitation

minLength1
maxLength255
email: string

Email address for the invitation

formatemail
expires_at: string

When the invitation expires

formatdate-time
organization_id: string

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

minLength1
maxLength255
role: OrganizationRole

Role that will be assigned when invitation is accepted

Accepts one of the following:
"org_admin"
"org_member"
"org_viewer"
status: InvitationStatus

Status of an invitation

Accepts one of the following:
"pending"
"accepted"
"expired"
"revoked"
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.

Create

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);
{
  "id": "ab3def8hij2klm9opq5rst7uvw",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": "ab3def8hij2klm9opq5rst7uvw",
  "email": "dev@stainless.com",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "organization_id": "ab3def8hij2klm9opq5rst7uvw",
  "role": "org_admin",
  "status": "pending",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}
Returns Examples
{
  "id": "ab3def8hij2klm9opq5rst7uvw",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": "ab3def8hij2klm9opq5rst7uvw",
  "email": "dev@stainless.com",
  "expires_at": "2019-12-27T18:11:19.117Z",
  "organization_id": "ab3def8hij2klm9opq5rst7uvw",
  "role": "org_admin",
  "status": "pending",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}