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):

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:

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 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:

   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, Step 2
4. Check Authentik logs:

   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

# 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