Authentik account recovery

Connect your self-hosted Authentik instance to Nametag to let employees securely reset their own passwords and multifactor authentication (MFA) devices after verifying their identity. The steps below cover connecting the directory. For the rest of the setup — self-service permissions, the self-service site, and monitoring — see the self-service account recovery administrator’s guide.

You will not enter any Nametag API key into Authentik. The only credential involved is one that Authentik issues, which you paste into Nametag.

Provision a connector credential in Authentik

Nametag needs a scoped service-account token to call your Authentik API.

Recommended — import the Nametag blueprint. On the Authentik setup screen in the Nametag console, select Download blueprint to save nametag.yaml. In Authentik, go to Customization → Blueprints, import that file, and apply it. It creates:

• a nametag-connector service account,
• a nametag-connector group that authorizes the service account to issue recovery links,
• an API token for that service account.

The blueprint generates the token for you — copy it (Authentik shows it once) and paste it into Nametag when you connect the directory (below).

Why the service account needs elevated access. Authentik’s recovery endpoint (POST /core/users/<pk>/recovery/) enforces an object-level permission check — it requires authentik_core.reset_user_password on the specific user being recovered. A globally-assigned permission does not satisfy that check for arbitrary users; only a superuser does. So the blueprint’s group is marked superuser. If your policy forbids a superuser service account, grant object-level reset_user_password (plus view_user) on the users in scope instead, and drop the superuser flag — but that does not scale to recovering any member.

Manual alternative.

1. Directory → Users → Create service account, named nametag-connector.
2. Directory → Groups → Create a group named nametag-connector, enable Is superuser, and add the service account to it. (Authentik’s recovery endpoint requires a superuser to issue links for any user; see above.)
3. On the service account, create a token (API token). Copy it.

Network reachability

Nametag reaches your Authentik instance over HTTPS at the base URL you provide.

• If your instance is internet-reachable: allowlist the published Nametag egress IP ranges so the connector can call it.
• If your instance is private: use the customer-side relay option (contact Nametag) so the connector can reach it without exposing Authentik publicly.

Plaintext HTTP is refused — the base URL must be https://.

Connect Authentik in the Nametag console

1. In the Nametag console, open Add Integration and choose Authentik.
2. On Connect to Authentik, enter your base URL (for example https://auth.example.com) and paste the API token you generated above, then submit. Nametag validates by making one read-only call to your instance; success means it’s reachable and the token works.
3. Configure self-service permissions to enable the Recover account action.

How recovery works

Authentik exposes a single Recover account action. After a user verifies their identity and selects it, Nametag asks Authentik for a one-time recovery link (POST /core/users/<pk>/recovery/) and sends the user straight to it. The user follows it into Authentik’s recovery flow to reset their password and re-enroll MFA. Nametag never sets a password or deletes authenticator devices.

The link is single-use; its lifetime is governed by your Authentik recovery flow token expiry (set that flow’s token to a short duration if you want a tight window — the endpoint has no per-request TTL).

What Nametag does and doesn’t store

• Does: an auditable record that a verification passed and which action was taken, bound to <tenant>:<authentik-user-id>.
• Doesn’t: any personal data in Authentik’s fields or storage. The verified identity stays in Nametag; Authentik receives only the request for a recovery link and issues the link itself.

Troubleshooting

• “Can’t reach authentik at …” — reachability or base URL problem. Confirm the URL is correct and HTTPS, and that the Nametag egress ranges are allowlisted (or the relay is configured).
• “Invalid credential” — the token is wrong or expired. Re-issue it with the blueprint (or on the service account) and reconnect.
• permission_denied / “You do not have permission to perform this action” — the recovery endpoint enforces an object-level authentik_core.reset_user_password check, which a globally-assigned permission does not satisfy; the service account must be a superuser (or hold that permission at the object level on the target user). Re-import the blueprint (its nametag-connector group has Is superuser enabled) and confirm the service account is a member of that group.
• User not found — the email/username didn’t resolve in Authentik; confirm the user exists and the lookup field matches.