authentik-watcher¶

authentik-watcher is a Telegram bot that notifies you when new users register via Authentik invitation links, and provides interactive commands to query invitations and recent registrations.

Without this bot, the only way to know someone used an invitation is to check the Authentik admin panel manually. authentik-watcher pushes a notification to Telegram the moment a new user is created, including which invitation they used, what groups they were assigned, and their library access level.

How It Works¶

graph LR
    Authentik -->|1. model_created event| Watcher[authentik-watcher]
    Watcher -->|2. GET /core/users/pk| Authentik
    Watcher -->|3. GET /stages/invitation/invitations/| Authentik
    Watcher -->|4. send notification| Telegram[Telegram Group]
    Telegram -->|5. /invites, /users| Watcher

Hold "Alt" / "Option" to enable pan & zoom

When a new user registers:

Authentik fires a model_created webhook via its notification rule system
authentik-watcher receives the event and fetches the new user's details from the Authentik API
Matches the user to the invitation that was used (by group overlap)
Sends a formatted notification to the shared Telegram admin group

The bot also responds to interactive Telegram commands for querying invitations and recent registrations.

Deployment¶

Namespace

bots
Source

gitea.hdhomelab.com/cicd/authentik-watcher
Config

flux/apps/noah/bots/authentik-watcher/
Port

8080 (cluster-internal only)

Telegram Commands¶

Command	Description
`/invites`	Lists all invitations as inline buttons. Tap one to see: link (copyable), uses remaining, expiry, creator, groups, and library access.
`/users`	Lists users registered in the last 7 days with their invitation source.

Notification Format¶

When a new user registers, the bot sends:

New User Registered

User: johndoe (John Doe)
Email: john@example.com
Groups: jellyfin_user, miniflux_user
Libraries: cn
Invitation: "Friends & Family" (by admin)
Registered: 2026-03-31 14:22 UTC

Invitation Detail Card¶

When you tap an invitation from /invites:

Invitation: Friends & Family

Link: https://auth.hdhomelab.com/if/flow/invitation-enrollment/?itoken=abc123
Expires: 2026-04-15
Single use: no
Created by: admin
Groups: jellyfin_user, miniflux_user
Libraries: cn

Configuration¶

Environment Variables¶

Env Var	Source	Value
`AUTHENTIK_URL`	Static	`http://authentik-server.infra.svc`
`AUTHENTIK_EXTERNAL_URL`	Static	`https://auth.hdhomelab.com`
`AUTHENTIK_TOKEN`	Vault secret	Authentik API token (read-only)
`TELEGRAM_TOKEN`	Vault secret	Telegram bot API token
`TELEGRAM_CHAT_ID`	Vault secret	Telegram group chat ID
`WEBHOOK_SECRET`	Vault secret	Shared secret for webhook validation

Vault Secrets¶

Create at path authentik-watcher in Vault:

Key	Description
`telegram-token`	Telegram bot token — from @BotFather
`telegram-chat-id`	Shared Telegram group ID (same group as seerr-approver)
`authentik-token`	Authentik API token — Admin → Directory → Tokens, intent: API Token, read-only
`webhook-secret`	Shared secret for validating Authentik webhook payloads — generate with `openssl rand -hex 32`

Authentik Event Rule¶

The webhook is triggered by an Authentik notification rule configured via Tofu (tofu/tf-deploy/authentik/notification_watcher.tf):

Resource	Name	Purpose
`authentik_policy_event_matcher`	`user-created`	Matches `model_created` events for `authentik_core.user`
`authentik_event_transport`	`authentik-watcher-webhook`	Webhook transport to `http://authentik-watcher.bots.svc:8080/webhook`
`authentik_event_rule`	`user-created-notify`	Binds the event matcher to the webhook transport

Cluster-internal only

The bot has no ingress or HTTPRoute. It only receives traffic from Authentik inside the cluster and makes outbound calls to the Telegram API.