Skip to main content

​
Overview

The Invitations API allows you to invite users to join organizations via email. Invitations are sent through WorkOS and can be managed (resent, revoked, or deleted) by authorized users. All invitation operations require authentication and appropriate organization permissions.

​
Invitation lifecycle

Invitations have the following states:
  • pending - Invitation sent, awaiting acceptance
  • accepted - User has accepted the invitation
  • expired - Invitation has expired (7 days after creation)
  • revoked - Invitation has been manually revoked

​
Create invitations

Creates one or more invitations to an organization. The inviter must have permission to invite users to the organization. This operation sends invitation emails via WorkOS.
​
organizationId
string
required
Organization ID to send invitations for.
​
invites
array
required
Array of invitation objects.

​
Response

​
results
array
required
Array of invitation results, one per invite.
​
successCount
number
required
Number of successfully created invitations.
​
errorCount
number
required
Number of failed invitations.

​
Errors

  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
This endpoint returns batch results. Individual invitation failures do not cause the entire request to fail. Check the success field on each result.
const result = yield* client.call("invitation.create", {
  organizationId: "org_123",
  invites: [
    { email: "[email protected]", role: "admin" },
    { email: "[email protected]", role: "member" }
  ]
});

console.log(`${result.successCount} invitations sent`);
console.log(`${result.errorCount} invitations failed`);

for (const result of result.results) {
  if (result.success) {
    console.log(`✓ Sent to ${result.email}`);
  } else {
    console.log(`✗ Failed for ${result.email}: ${result.error}`);
  }
}

​
Resend invitation

Resends an existing invitation via WorkOS. Only the invitation creator or organization admins can resend invitations.
​
invitationId
string
required
Invitation ID to resend.

​
Response

​
data
object
required
The invitation object (same structure as in create invitations).
​
transactionId
string
required
Transaction ID for optimistic UI updates.

​
Errors

  • InvitationNotFoundError - Invitation does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("invitation.resend", {
  invitationId: "inv_123"
});

​
Revoke invitation

Revokes an existing invitation via WorkOS. The invitation status is updated to "revoked". Only the invitation creator or organization admins can revoke invitations.
​
invitationId
string
required
Invitation ID to revoke.

​
Response

​
transactionId
string
required
Transaction ID for optimistic UI updates.

​
Errors

  • InvitationNotFoundError - Invitation does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("invitation.revoke", {
  invitationId: "inv_123"
});

​
Update invitation

Updates an existing invitation. Can be used to change invitation status, role, or other properties.
​
id
string
required
Invitation ID to update.
​
status
string
New status: "pending", "accepted", "expired", or "revoked".
​
acceptedAt
string
ISO 8601 timestamp of acceptance.
​
acceptedBy
string
User ID who accepted the invitation.

​
Response

​
data
object
required
The updated invitation object.
​
transactionId
string
required
Transaction ID for optimistic UI updates.

​
Errors

  • InvitationNotFoundError - Invitation does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("invitation.update", {
  id: "inv_123",
  status: "accepted",
  acceptedAt: new Date().toISOString(),
  acceptedBy: "user_456"
});

​
Delete invitation

Deletes an invitation. Only the invitation creator or users with appropriate permissions can delete invitations.
​
id
string
required
Invitation ID to delete.

​
Response

​
transactionId
string
required
Transaction ID for optimistic UI updates.

​
Errors

  • InvitationNotFoundError - Invitation does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("invitation.delete", {
  id: "inv_123"
});

Organizations

Manage organizations and settings

Organization members

Manage organization members and roles

Build docs developers (and LLMs) love

Get started for freeTalk to us