# Inviting people

> Invite a named person by email with a role and an end date. The invitation is a time-limited sign-in rule.

An invitation gives one named person access to the tenant for a set period, for example an auditor, a contractor or a colleague outside the directory. Invitations are managed at **Access → Invitations**.

## Requirements

| Requirement  | Detail                                                                                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Role         | `client_admin`, signed in as a person                                                                                               |
| Invitee      | An email address. Atlantic staff cannot be invited; their access is set separately on the **Access** page                           |
| Reachability | Where the tenant does not offer the one-time PIN, the address’s domain must be admitted by a sign-in rule for the identity provider |

## Effect of an invitation

Sending an invitation:

1. adds a **Named person** sign-in rule for the email address, with the chosen role and end date;
2. where the tenant offers the one-time PIN, adds the address to the PIN’s Cloudflare Access policy;
3. sends the person an email in the tenant’s language, naming the administrator who sent it and giving the portal address.

The email contains no link token or other credential. The person signs in through Cloudflare Access, with a one-time PIN sent to their own mailbox or through the organisation’s identity provider.

## Procedure

1. Under **Invite someone**, enter the **Email address**.

2. Choose the **Role**. The default is `viewer`. Choosing `client_admin` displays a warning: a client administrator can change who signs in, issue keys and read the audit log. See [Roles](/api/roles/).

3. Set **Access for**, in days: 30 by default, from 1 to 366.

4. Optionally add a **Note**, up to 160 characters.

5. Choose **Send invitation**.

   Result: the invitation is listed as **Pending**, with the sign-in method that applies to it. If the email cannot be delivered, the invitation is still created; give the person the portal address directly.

## Sign-in method

| Tenant configuration               | Sign-in                                                                                                                                                                          |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The tenant offers the one-time PIN | The person enters their address at sign-in and receives a one-time code                                                                                                          |
| The tenant does not offer the PIN  | Only addresses whose domain is admitted by a sign-in rule can be invited. Other addresses are refused with `not_reachable`; add the person through the identity provider instead |

## States

| State            | Meaning                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| **Pending**      | Sent; the person has not signed in                                                                   |
| **Accepted**     | The person has signed in                                                                             |
| **Expired**      | The end date has passed. The rule’s expiry is checked on every request, and access ends on that date |
| **Revoked**      | A client administrator revoked the invitation                                                        |
| **Rule removed** | The sign-in rule behind it was removed on the **Access** page                                        |

**Revoke** removes the sign-in rule, removes the address from the one-time PIN policy where the invitation added it, and erases the person’s profile.

## Limits

| Limit                  | Value                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Duration               | 1 to 366 days; default 30                                                                                          |
| Invitations per tenant | 50 per day; the page shows the number remaining                                                                    |
| Repeat invitation      | Refused while an invitation to the same address is pending                                                         |
| Public mailboxes       | Accepted for a named person (such as a `gmail.com` address). Public mail domains are refused only for domain rules |
| Client administrators  | At least one must remain                                                                                           |

## API

| Route                             | Role                     | Action                                                           |
| --------------------------------- | ------------------------ | ---------------------------------------------------------------- |
| `GET /api/v1/invitations`         | `client_admin`           | Lists every invitation and its state                             |
| `POST /api/v1/invitations`        | `client_admin`, a person | Sends an invitation: `{"email", "role", "expires_days", "note"}` |
| `DELETE /api/v1/invitations/{id}` | `client_admin`, a person | Revokes the invitation                                           |

## Audit

Each invitation sent, accepted and revoked is recorded in the tenant’s audit log as `invitation_sent`, `invitation_accepted` or `invitation_revoked`.

Source: https://docs.atlanticagenticlabs.com/enterprise/invitations/