1. Docs
  2. Invitations

Invitations

How a new person joins the part of the organization you administer, and what you can do about an invitation after it has been sent.

Overview

An invitation is the ordinary way someone becomes one of the people you administer. You send it, they accept it, and they arrive already holding the role you chose, in the place you chose. Nothing exists in the directory until they accept.

Sending an invitation and managing the ones already sent are two separate capabilities. An administrator who can send but not manage can bring someone in, but cannot see the list of outstanding invitations afterwards.

Sending one

You supply three things, and two of them are bounded by your own authority. That is the whole form: everything else about the person follows from the role and the place.

Their email address, and their name.The role they should arrive with, chosen from the roles you are permitted to grant.The place they should arrive in, chosen from the places you administer. You cannot invite someone above or beside your own responsibility.

What the recipient gets

They get an email with a link that is theirs alone and works once. Someone new to your organization sets a password as they accept, and arrives holding the role you chose. Someone who already exists elsewhere in the account signs in with the password they already have, and the invitation simply adds them where you invited them. Either way the link is good for seven days.

Resending and revoking

Resending sends a fresh email with a new link and gives it another seven days. The previous link stops working at that moment, which is the point: a forwarded or leaked link is retired by resending. There is a five-minute cooldown between resends so a repeated click cannot flood someone's inbox. An invitation that has expired can be resent in the same way, which is how you invite that address again. Revoking retires the link without sending anything, and can be done at any time before it is accepted.

Neither one deletes a record. An invitation is always in one of four states, pending, accepted, expired, or revoked, and a revoked one stays visible as revoked, which is what lets you answer later whether someone was ever invited.

Next Step

An invitation arrives carrying a role. Assigning access explains where that role comes from and how to change it afterwards.

Environment
API version
v1.0
On this page Was this page helpful?

Tell us how we can improve this guide.