Skip to main content
Pulumi logo Pulumi logo
25.6K Contact us Sign in Dashboard Get started
  1. Docs
  2. Reference
  3. REST API Docs
  4. Invites

Invites

    List Org Invites

    ▼
    GET /api/orgs/{orgName}/invites

    Lists all pending invitations for an organization. Pending invitations count toward the organization’s seat limit, since they reserve capacity for the users who eventually accept. Each entry includes the invite ID, recipient email, role assignment, sender, and the timestamp when it was last sent.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: ListOrganizationInvitesResponse
    • invites array[PendingOrganizationInvite] required
      The list of pending organization invites
    • ↳ id string required
      ID is the internal ID of the invite. Used to refer to this invite later to accept/cancel.
    • ↳ email string required
      The email address the invite was sent to.
    • ↳ role enum required
      Role is the new role to give the member. Must be one of MEMBER, ADMIN, or BILLING MANAGER.
      Values:
      none — None
      OrganizationRoleNone describes the role of non-members.
      member — Member
      OrganizationRoleMember is the role for regular members.
      admin — Admin
      OrganizationRoleAdmin is the role for admins.
      potential-member — PotentialMember
      OrganizationRolePotentialMember is the role for users who are explicitly not a member of the organization, but are a member of the backing org on the 3rd party identity provider. (i.e. they could join the org.)
      stack-collaborator — StackCollaborator
      OrganizationRoleStackCollaborator is the role for users who are not a member of an organization, but have been explicitly granted access to some of the organization’s stacks. So they have limited permissions to access the org’s data.
      billing-manager — BillingManager
      OrganizationRoleBillingManager is the role for billing admins.
    • ↳ sentBy UserInfo required
      The user who sent the invite.
    • ↳ sentAt integer required
      SentAt is the timestamp when the invite was first sent.
    • ↳ acceptInviteUrl string required
      AcceptInviteURL is the url where a user would go to accept an invite to an organization.
    • ↳ acceptError string optional
      AcceptError is the most recent error a user has hit while trying to accept an organization invite. By default it is null.
    • ↳ status string required
      The friendly name of the invite status. Valid values are “pending”, “accepted”, “expired”, and “canceled”.
    • ↳ roleId string optional
      RoleID is the optional UUID of a custom role assigned to this invite.

    Get Org Invite

    ▼
    GET /api/orgs/{orgName}/invites/{inviteID}

    Validates the organization name and invite ID from the URL and, if they correspond to an active invitation, returns basic organization metadata. This provides a reasonably secure way to share organization metadata with a non-member without making it available to everyone, since the caller must know both the organization login and the invite ID. Returns 404 if the invite has already been accepted or canceled.

    Request Parameters

    • orgName string path required
      The organization name
    • inviteID string path required
      The invite identifier

    Responses

    200 OK
    Schema: OrganizationSummaryWithRole
    • name string required
      The name of the organization.
    • role enum required
      The role of the user within this organization.
      Values:
      none — None
      OrganizationRoleNone describes the role of non-members.
      member — Member
      OrganizationRoleMember is the role for regular members.
      admin — Admin
      OrganizationRoleAdmin is the role for admins.
      potential-member — PotentialMember
      OrganizationRolePotentialMember is the role for users who are explicitly not a member of the organization, but are a member of the backing org on the 3rd party identity provider. (i.e. they could join the org.)
      stack-collaborator — StackCollaborator
      OrganizationRoleStackCollaborator is the role for users who are not a member of an organization, but have been explicitly granted access to some of the organization’s stacks. So they have limited permissions to access the org’s data.
      billing-manager — BillingManager
      OrganizationRoleBillingManager is the role for billing admins.
    • githubLogin string required
      The GitHub login associated with the organization.
    • avatarUrl string required
      The URL of the organization’s avatar image.
    • email string optional
      The user’s email address. It is only populated on selected endpoints and is omitted from most responses. Treat it as sensitive information.
    Errors: 404 Invite

    Accept Org Invite

    ▼
    PATCH /api/orgs/{orgName}/invites/{inviteID}

    Accepts an organization invitation. The authenticated user making the request will be added as a member of the organization. IMPORTANT: if the URL used to accept the invite is disclosed, anybody else with a Pulumi account can accept/claim it. Returns 409 if the invite is not in the ‘invited’ state (already accepted or canceled).

    Request Parameters

    • orgName string path required
      The organization name
    • inviteID string path required
      The invite identifier

    Responses

    204 No Content
    Errors: 409 Invite is not in the 'invited' state

    Cancel Org Invite

    ▼
    DELETE /api/orgs/{orgName}/invites/{inviteID}

    Cancels a pending organization invitation, reclaiming the seat it reserves in the organization. Pending invitations count toward the organization’s seat limit, so canceling frees up capacity for new invitations or members. Returns 404 if the invite does not exist.

    Request Parameters

    • orgName string path required
      The organization name
    • inviteID string path required
      The invite identifier

    Responses

    204 No Content
    Errors: 404 Invite

    Resend Org Invite

    ▼
    POST /api/orgs/{orgName}/invites/{inviteID}/resend

    Resends an existing organization invitation. Sends another invitation email and updates the ‘sent’ timestamp to the current time. The sender of the resent invite may differ from the original sender. Returns 404 if the invite has already been accepted or canceled.

    Request Parameters

    • orgName string path required
      The organization name
    • inviteID string path required
      The invite identifier

    Request Body

    Schema: ResendOrganizationInviteRequest
    • token string optional
      Turnstile token

    Responses

    204 No Content
    Errors: 404 Invite

    Batch Create Org Invite Email

    ▼
    POST /api/orgs/{orgName}/invites/batch

    Creates multiple organization invitations in a single request and sends email notifications to each invitee. Each invitation includes a role assignment (admin or member) and optional team assignments. Pending invitations count toward the organization’s seat limit. The request body size is limited to prevent abuse.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: BatchCreateOrganizationInviteRequest

    Responses

    200 OK
    Schema: BatchCreateOrganizationInviteResponse
    • sentInvites array[CreateOrganizationInviteResponse] required
      List of sent invites
    • ↳ id string required
      The unique identifier
    • ↳ acceptInviteUrl string required
      The accept invite URL
    • failedInvites array[CreateOrganizationInviteRequest] required
      List of failed invites
    • ↳ email string optional
      The email address. Required for email-based invites, omitted when creating shareable invite links.
    • ↳ role enum required
      Built-in role to assign to the invited member. When ‘roleId’ is also supplied it takes precedence and this field is ignored; prefer ‘roleId’ for new integrations.
      Values:
      member — Member
      Regular organization member.
      admin — Admin
      Organization administrator.
      billing-manager — BillingManager
      Billing administrator.
    • ↳ roleId string optional
      UUID of a role (built-in or custom) to assign to the invited member. Takes precedence over ‘role’ when both are supplied.
    Errors: 400 Invalid email address.

    Create Org Invite Link

    ▼
    POST /api/orgs/{orgName}/invites/link

    Generates a new invite URL to join an organization, intended to be shared via copy/paste. Does not send out an email and does not require an email address in the request. Anyone with a Pulumi account who knows the resulting URL can accept the invitation, so share the link only with the intended recipient.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: CreateOrganizationInviteRequest
    • email string optional
      The email address. Required for email-based invites, omitted when creating shareable invite links.
    • role enum required
      Built-in role to assign to the invited member. When ‘roleId’ is also supplied it takes precedence and this field is ignored; prefer ‘roleId’ for new integrations.
      Values:
      member — Member
      Regular organization member.
      admin — Admin
      Organization administrator.
      billing-manager — BillingManager
      Billing administrator.
    • roleId string optional
      UUID of a role (built-in or custom) to assign to the invited member. Takes precedence over ‘role’ when both are supplied.

    Responses

    200 OK
    Schema: CreateOrganizationInviteResponse
    • id string required
      The unique identifier
    • acceptInviteUrl string required
      The accept invite URL

    Batch Create Org Unverified Invite Email

    ▼
    POST /api/orgs/{orgName}/invites/unverified/batch

    Creates multiple organization invitations for email addresses that may not yet have Pulumi accounts. Unlike the standard batch invite, this does not require the invitees to have verified email addresses. The invitee will be prompted to create an account when they accept the invitation.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: BatchCreateOrganizationInviteRequest

    Responses

    200 OK
    Schema: BatchCreateOrganizationInviteResponse
    • sentInvites array[CreateOrganizationInviteResponse] required
      List of sent invites
    • ↳ id string required
      The unique identifier
    • ↳ acceptInviteUrl string required
      The accept invite URL
    • failedInvites array[CreateOrganizationInviteRequest] required
      List of failed invites
    • ↳ email string optional
      The email address. Required for email-based invites, omitted when creating shareable invite links.
    • ↳ role enum required
      Built-in role to assign to the invited member. When ‘roleId’ is also supplied it takes precedence and this field is ignored; prefer ‘roleId’ for new integrations.
      Values:
      member — Member
      Regular organization member.
      admin — Admin
      Organization administrator.
      billing-manager — BillingManager
      Billing administrator.
    • ↳ roleId string optional
      UUID of a role (built-in or custom) to assign to the invited member. Takes precedence over ‘role’ when both are supplied.
    Errors: 400 Invalid email address.

      The infrastructure as code platform for any cloud.

      Contact us Get started