# Invite a person

Invite a colleague by email address, with a preset role or a group or role of your own, and follow up on invitations nobody has accepted.

The person signs in with their own email address and becomes a member of your organization, with
an IAM user that holds the access you chose. Replace jane.doe@example.com with their
address.

## Prerequisites

- Permission for `iam:InviteUser`.
- For the console, also `iam:ListMembers`: without it **Members** shows only "You do not have
  permission to list members." For **Custom**, `iam:ListGroups` or `iam:ListRoles` fills the list
  of groups and roles to choose from.
- To pass the link on yourself, `iam:GetInvitationLink`; to send it again, `iam:ResendInvitation`;
  to cancel it, `iam:CancelInvitation`.
- For **Custom**, the group or role exists; see [Create a group](create-a-group.md) or
  [Create a role](create-a-role.md).

## Send the invitation

**Console**
1. Open **Settings**, then choose **Members**.
2. Choose **Invite member**.
3. Enter the email address.
4. Choose the access: **Admin**, **Member** (the default), **Viewer**, **Billing**, **No access** or
   **Custom**. For **Custom**, also choose the group or role the person gets.
5. Choose **Send invitation**. The console says the invitation was sent and when the link expires.

**CLI**
```sh
dcloud iam invitations create --email jane.doe@example.com --role viewer
```

**API**
```http
POST /iam/api/invitations
{ "email": "jane.doe@example.com", "role": "none", "groupId": "3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f" }
```

## Result

The person gets an email with a link that is valid for 7 days. What they hold once they join:

| Access    | Policy attached to their IAM user         |
| --------- | ----------------------------------------- |
| Admin     | `PowerUserAccess`                         |
| Member    | `DeveloperAccess`                         |
| Viewer    | `ReadOnlyAccess`                          |
| Billing   | `BillingFullAccess`                       |
| No access | nothing                                   |
| Custom    | nothing, plus the group or role you chose |

Through the API, `groupId` and `roleId` can be given with any `role`. Attach more afterwards on their
IAM user; see [Attach a policy](attach-a-policy.md).

When the address cannot be mailed (an earlier hard bounce or spam complaint), the invitation is
still created: the console says that no email was sent, with the reason, and shows the link for you
to send yourself. The API returns the link as `inviteUrl` and the reason as `mailNotSent`.

Someone who was a member before and is invited again gets the same IAM user back, without the
policies, groups and roles it held before.

## What the invited person does

The link opens a page that names who invited them, the organization and the access they get.

- **Without an account**, they enter their name and a password and choose **Join** _organization_.
  That creates the account, joins your organization and opens the console in it. No organization of
  their own is created.
- **With an account**, they sign in with that address and join without a further step.
- **If your organization enforces single sign-on** for the address's domain, the page offers only
  **Continue with** _provider_; they join on the way back.
- **Already signed in to the console with an organization of their own**, they also see the
  invitation as a banner with **Join** _organization_.

A link that was used, cancelled or has expired opens **Invitation unavailable**, which says which.
Someone signed in with a different address is told so, with a button to sign in as someone else.

## Follow up on an invitation

On **Members**, a pending invitation has its own row, with the date its link expires. Its row menu
offers:

- **Copy link**: the link works only for the invited address.
- **Resend**: mails the link again and makes it valid for 7 days from now. On an expired invitation
  the item reads **Resend (renews the link)**.
- **Cancel invitation**, then confirm with **Cancel invitation**.

The access an invitation carries cannot be changed once it is sent. Cancel it and invite again.

## If the invitation is refused

- 404 `No such group` or `No such role` for a `groupId` or `roleId` that is not in your organization.
- Accepting through the API (`POST /iam/api/invitations/accept` with the link's token), where the
  invitation page's own checks do not run first: 400 `Invitation not found or already used`,
  `Invitation has expired`, or `This invitation was sent to a different email address`, checked in
  that order; and 403 `An IAM user cannot accept invitations. Sign in with your own email
account.` before any of them, when the session belongs to an organization's user name instead of
  a person's email address.

## Related

- [Manage members](manage-members.md)
- [Principals and policies](principals-and-policies.md)
- `iam.invitations.create` · `dcloud iam invitations create`
