Any time a new user needs to be invited to Echo6 services. Invitations create a time-limited enrollment link that lets the invitee set up their own username and password.
- For email mode: SMTP must be configured and working (no-reply@echo6.co via Mailcow)
---
## Mode 1: Invite via Email (Automatic)
The invitation email is sent automatically when the invitation is created with an `email` field in custom attributes.
### Steps
1. Log in to https://auth.echo6.co as admin
2. Navigate to **Directory → Invitations → Create**
3. Fill in:
| Field | Value |
|-------|-------|
| Name | Descriptive name (e.g., `jane-smith-2026-02`) |
| Flow | **Invitation Enrollment** |
| Single use | **On** (recommended) |
| Expires | Set appropriately (e.g., 7 days from now) |
4. In **Custom attributes** (YAML format):
```yaml
name: Jane Smith
email: jane@example.com
```
5. Click **Create**
The expression policy (`invitation-email-sender`) detects the `email` field and calls `ak_send_email()` to deliver the enrollment link to the invitee. The email includes the invitation URL with the `?itoken=` parameter.
### What the Invitee Receives
- Email from `no-reply@echo6.co` with subject "You've been invited to join Echo6"
- Contains a link to `https://auth.echo6.co/if/flow/invitation-enrollment/?itoken=<token>`
- The link takes them through the enrollment flow: accept invitation → set username/password → auto-login
---
## Mode 2: Invite via Link (Manual)
For cases where you want to share the link yourself (Slack, Signal, in person, etc.), omit the `email` field.
### Steps
1. Log in to https://auth.echo6.co as admin
2. Navigate to **Directory → Invitations → Create**
3. Fill in:
| Field | Value |
|-------|-------|
| Name | Descriptive name (e.g., `jane-smith-link`) |
| Flow | **Invitation Enrollment** |
| Single use | **On** (recommended) |
| Expires | Set appropriately |
4.**Custom attributes** — either leave empty `{}` or include only the name:
```yaml
name: Jane Smith
```
Do **not** include an `email` field — this prevents the automatic email from being sent.
5. Click **Create**
6. In the invitation list, **expand the row** to reveal the invitation link
7. Copy and share the link manually
---
## Custom Attributes Reference
| Field | Required | Purpose |
|-------|----------|---------|
| `name` | No | Pre-fills the invitee's display name (if enrollment flow uses it) |
| `email` | No | Triggers automatic email delivery. Omit for link-sharing mode |
Only `email` affects system behavior. Any other fields are stored as metadata on the invitation.
---
## Best Practices
### Expiry
- **Email invitations:** 7 days is reasonable — gives time for the email to arrive and the user to act
- **Link invitations:** 24–48 hours if sharing in real-time; 7 days if async
- **Never use no-expiry** — orphaned invitations are a security risk
### Single Use
- **Always enable** for individual invitations — prevents link reuse after the invitee enrolls
- Only disable if you're creating a batch enrollment link for a group (rare)
### Naming Convention
Use `firstname-lastname-YYYY-MM` or `purpose-YYYY-MM` for easy identification:
3.**Check Mailcow authsource** — if SMTP auth fails, the no-reply@echo6.co mailbox may have reverted to `generic-oidc`. See [Mailcow Create Mailbox runbook](mailcow-create-mailbox.md), Step 2
