Skip to main content

Create invites

POST https://api.rollstack.com/public/v1/invites

Invites up to 50 users as admins or members. Only emails in the organization's allowed domains are invited, and it fails with a 400 while the organization has none. Returns the invites it created and the emails it rejected, with the reason: outside the allowed domains, already a member or already invited.

Requires the users:write scope. Only owners and admins of the organization may call it.

Operation ID: createInvites. Only owners and admins can call it.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • emails (array of string (email), required): The email addresses to invite. Each one on the organization's domain allowlist (allowedDomains) that doesn't belong to a member and isn't already invited gets an invite and an invitation email; the others come back in rejected. From 1 to 50 addresses, each listed once, ignoring case.
  • role (string, required): The role the invited people get when they join: admin lets them manage the organization's settings, members and invites, and member lets them use Rollstack without managing the organization. A key can't invite owners. One of admin, member.
  • authenticationRole (string): Gives the invited people access to the organization's Authentication settings (Single Sign-On and SCIM provisioning) once they join: viewer can see them, editor can also change them. If omitted, they join without access. Only owners can set it, not admins. One of viewer, editor.

Response 201

Success

application/json

  • invited (array of object, required): The invites created, one for each email that passed the checks. Rollstack emails each person an invitation to join.
    • id (string, required): Unique identifier for the invite. Pass it as inviteId to deleteInvite to cancel the invite.
    • email (string, required): The email address invited to join the organization.
    • role (string, required): The role the person gets when they accept the invite. owner can do everything in the organization, admin manages its settings, members and invites, and member uses Rollstack without managing the organization. One of owner, admin, member.
    • authenticationRole (string or null, required): The access to the organization's Authentication settings (Single Sign-On and SCIM provisioning) the person gets when they accept the invite: viewer can see them, editor can also change them, and null gives none. One of viewer, editor.
    • createdAt (string (date-time), required): When the person was invited.
  • rejected (array of object, required): The emails that were not invited, each with the reason. The other emails in the request were still invited.
    • email (string, required): An email from your request that was not invited, in lowercase.
    • reason (string, required): Why the email was not invited. domain_not_allowed: its domain isn't on the organization's allowedDomains. already_member: it belongs to a member of the organization, active or deactivated; reactivate a deactivated one with reactivateMember. already_invited: it already has a pending invite, listed by listInvites. One of domain_not_allowed, already_member, already_invited.