Invitations

Enterprise feature. This capability is available on Polyant Enterprise deployments.

The Invitations screen (/invitations) adds 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.

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.
• Organization role — one of the four system roles.
• 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 response contains the invite token once. Nothing is emailed by the engine: hand the link over yourself, treating it like a password.

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.

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, so the page can send them to sign-in instead of signup. That flag is exposed for the token’s single email only; it is not a general “does this user exist” oracle.
2. Sign up. The invitee sets a password and the account is created. An email that already has an account is refused here, 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 — the roles you are handing out, and the guards on them.
• Workspaces — why a Member or Viewer invite needs a workspace.
• Users — the platform-level alternative when invitations are unavailable.
• Authentication — what the new account signs in with.