echo6-docs/runbooks/authentik-create-invitation.md

# Authentik: Create Invitation

Create user invitations via the Authentik Admin UI. Supports two modes: email (automatic delivery) and link-sharing (manual delivery).

---

## When to Use This

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.

---

## Prerequisites

- Authentik admin access at https://auth.echo6.co
- 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:
- `jane-smith-2026-02`
- `jodie-media-access-2026-02`
- `batch-beta-testers-2026-03`

---

## After Enrollment

New users are created under the `users/enrolled` path. To grant them access to services:

1. Navigate to **Directory → Groups**
2. Add the user to the appropriate group(s):

| Group | Grants Access To |
|-------|-----------------|
| media-users | Jellyfin, Jellyseer, PeerTube |
| ai-users | Open WebUI |
| cloud-users | Immich, Nextcloud |
| communication-users | Mailcow, Matrix |

See the [Access Groups runbook](authentik-access-groups.md) for detailed group management procedures.

---

## Troubleshooting

### Email not sent (email mode)

1. **Check custom attributes** — the `email` field must be present and correctly formatted
2. **Check SMTP** — verify Authentik can send email:
   ```bash
   ssh root@100.64.0.1
   docker exec authentik-server ak test_email matt@echo6.co
   ```
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
4. **Check Authentik logs**:
   ```bash
   docker compose -f /opt/authentik/docker-compose.yml logs server --since 5m 2>&1 | grep -i email
   ```

### "Invalid invite/invite not found" when clicking link

- The invitation has expired or was already used (single-use)
- The invitation was deleted
- The `?itoken=` parameter is missing or malformed in the URL

### User enrolled but can't access any apps

- The user needs to be added to at least one service group (see "After Enrollment" above)
- By default, enrolled users have no group memberships

---

## Managing Existing Invitations

### View All Invitations

Admin UI → **Directory → Invitations** — shows all active invitations with name, expiry, and usage status.

### Delete an Invitation

Click the trash icon next to the invitation. This immediately invalidates the link — anyone who hasn't enrolled yet will see "Invalid invite."

### Via API

```bash
# List all invitations
curl -s "https://auth.echo6.co/api/v3/stages/invitation/invitations/" \
  -H "Authorization: Bearer $AUTHENTIK_API_TOKEN" | python3 -m json.tool

# Delete by PK
curl -s -X DELETE "https://auth.echo6.co/api/v3/stages/invitation/invitations/<PK>/" \
  -H "Authorization: Bearer $AUTHENTIK_API_TOKEN"
```

---

## Checklist

```
[ ] Invitation created with correct flow (Invitation Enrollment)
[ ] Single use enabled
[ ] Expiry set appropriately
[ ] Email mode: email field in custom attributes, delivery confirmed
[ ] Link mode: link copied and shared manually
[ ] After enrollment: user added to appropriate groups
```

---

*Created: 2026-02-16*