Invitations

Managed services. This capability is available with Polyant managed services.

Invitations add people to an organization by sending them a token link. The invitee creates their own credentials, so no operator ever handles someone else’s password.

They are issued from Members and roles in Settings → Organization - inviting someone and administering who is already there are one job, on one page.

Listing, creating, and revoking all require org.member:manage - Admin and above. The whole surface is refused outright on a deployment without the invitations feature.

Creating an invitation

You supply:

• Email - normalised, and authoritative end to end. The invitee never gets to change it, and an invitation can only be accepted by that address. If the organization declares SSO domains, an address outside them is refused here, naming the domains that are admitted. That is deliberate: at accept time the invitee still has no membership, so the sign-in gate lets them through - and would refuse them from their next Google sign-in onward, once accepting had given them the membership that makes the list apply. Failing at creation means the invitation that cannot work never exists. To onboard an outside address, add its domain to the organization’s list first.
• Organization role - Admin, Member or Viewer, or any of the organization’s custom roles. Owner is deliberately not invitable: the most privileged standing in a tenant is granted to someone already in it, not handed to an unclaimed mailbox.
• Workspace target and workspace role - optional in general, but required for a Member or Viewer invite: without a workspace they would land in the organization able to see no workspaces at all. The two must be supplied together. The requirement keys off those two role names literally, so a custom role of comparable standing does not trigger it - supply a workspace anyway, or the invitee arrives with nothing to look at.

The response contains the invite token once.

Whether it is also emailed depends on the installation - outbound email ships in the managed-services build. With a mailer configured the engine mails the link to the invited address; with none it still returns the link and reports emailSent: false, so an operator always has a working path - hand it over yourself, treating it like a password. What never happens is a silent no-op: the engine does not pretend to have sent mail. The mailer is configured at Installation policies, not in the environment.

The token is stored only as a hash, so the plaintext cannot be recovered from the database - a lost link means revoking and re-issuing.

Minting tokens is the brute-force-sensitive operation, so POST is limited to 5 requests/minute while the read and revoke paths get 30.

A Platform Admin adding themself

When a Platform Admin adds their own address, no invitation is created and no email is sent: they join directly with the organization role they picked, and with the workspace and workspace role when they chose one. An invitation exists to obtain the invitee’s consent, and someone adding themself has given it. The join goes through the same checks as granting a role from the member list, the SSO domains included, is audited as a role assignment, and the API answers { joined } instead of { invitation }.

This applies only to a Platform Admin acting from a session or from a personal token minted with platform standing, and only to their own address. Every other address, an existing user’s included, still gets an invitation.

Lifecycle

An invitation is pending until it is accepted, revoked, or expires. The default lifetime is 7 days.

Every terminal state answers with the same status (410 Gone) and a distinct message - revoked, already used, or expired - so a token holder learns why it failed without the API leaking whether some other token exists.

Revoke a pending invitation from the list. Revoking one that is already accepted or gone is reported as “nothing pending to revoke” rather than silently succeeding.

What the invitee does

The invite link is public, and it is deliberately narrow:

1. Preview. The page reveals only the invited email, the organization and workspace names, and the roles offered - plus whether an account already exists for that email and which sign-in methods it has: a password, Google, or both. Those facts are exposed for the token’s single email only, and only once the token is known to be valid; they are not a general “does this user exist” oracle.
2. Sign in or sign up. What the page offers follows from the preview and from the browser’s current session:
   • already signed in as the invited address: one click accepts;
   • signed in as someone else: the page says so and offers to switch account;
   • signed out, with an existing account: Sign in with Google & join when the deployment offers Google and the account is linked to it or has no password, and the password form only when the account has a password. A Google-only account can therefore accept, and a Google sign-in started from the page completes the acceptance on return. A Google sign-in is admitted while the invitation is pending even though the invitee is a member of nothing yet; see Who may sign in with Google;
   • no account: the invitee sets a password and the account is created. An email that already has an account is refused at signup, so an invite can never be used as a password reset.
3. Accept. The membership and the organization role binding are created, plus the workspace binding when one was included.

Both public endpoints are tightly rate-limited.

Two details worth knowing when something looks off:

• The token is consumed before any membership is written, so two concurrent accepts cannot both grant access.
• If the invited workspace was deleted between issuing and accepting, the invitation degrades to the organization role alone rather than failing.

See also

• Members and roles - the page this is issued from, and the guards on the roles you hand out.
• Workspaces - why a Member or Viewer invite needs a workspace.
• Platform members - the installation-level alternative when invitations are unavailable.
• Authentication - what the new account signs in with.