How a recovery key restores authentik admin access
A recovery key created with ak create_recovery_key gives time-limited, direct access to an authentik instance, so an administrator can get back in and restore control. Teams reach for it when the normal sign-in path is broken: a misconfigured stage locks out every login, a flow import replaces a working flow with a broken one, or the akadmin credentials are lost. The key is an emergency path, not a login method. Anyone who holds the link can use it while it is valid, so it should be issued only when someone with authority over the instance has confirmed the need and should be used only long enough to repair the damage.
Since authentik 2025.10, the duration you pass to ak create_recovery_key is set in minutes instead of years, as described in the authentik 2025.10 release notes. Scripts, runbooks or notes written for earlier versions that assume a long validity period will now produce keys that expire quickly, so check the duration argument against the version you run before relying on an old procedure. Confirm the exact syntax for your version in the login troubleshooting guide before the incident, not during it.
The key only buys time. Once you are inside, find the change that caused the lockout, such as the stage binding, flow or policy, and correct it, then test a normal sign-in with a second administrator account before closing the session. Record who created the key, when it was used and what was changed, because those entries are the evidence your reviewers will ask for. If the key was created for a stage or flow that others depend on, check that the fix does not reopen the same lockout on the next import.
Creating a recovery key with ak create_recovery_key on Docker or Kubernetes
This sequence produces a short-lived, single-purpose link that gives direct access to the akadmin account so you can repair the broken flow or configuration that locked you out. It is meant to be run by someone with shell access to the authentik host or cluster, and the output should be handled as a credential.
Confirm the deployment and target account
Before running anything, confirm which authentik deployment is affected, whether it runs under Docker Compose or Kubernetes, and which account you need back. The authentik troubleshooting documentation uses akadmin as the example, so the command in this sequence targets that account. Check that you can reach the host or cluster through an approved access path and that you know the name of the worker container or pod. Record the change ticket or incident reference that authorizes the recovery, because the link grants direct admin access. Done when you have the deployment type, the account name and the authorizing reference written down.
Open a shell on the worker container
Run the command from the worker, not the server, because the documented method uses the worker container. On Docker Compose, use the compose project directory and run the recovery command through docker compose run against the worker service. On Kubernetes, identify the running worker pod with kubectl get pods and open a shell with kubectl exec. Confirm you are in the expected environment by checking the hostname or namespace before continuing. Done when the prompt shows the worker container or pod you intended to use.
Set the recovery duration in minutes
Run ak create_recovery_key with the target account and a duration. Since authentik 2025.10 the duration argument is in minutes instead of years, so a value copied from older documentation or scripts will produce a far longer window than intended. Choose the shortest duration that lets one person complete the repair, and confirm the unit against your installed version's release notes before running it. Done when the command is entered with the account name and a duration in minutes, and you have verified the unit.
Copy the generated link securely
The command prints a recovery link. Anyone holding that link can sign in as the target account until it expires, so copy it directly into your password manager or a secure channel, not into a chat, ticket or wiki. Avoid pasting the link into a shell prompt or a command that shell history would record. If you use a terminal multiplexer or session recording, check that it is not capturing this output. Done when the link is stored in a location your team controls and only the intended operator has it.
Verify the link works in a private session
Open the link in a private browser window to avoid mixing it with an existing session. Confirm you land in the admin interface as the target account and that the account's permissions match what you expect for the repair. Do not change unrelated settings while you are signed in through the link. Done when you can view the admin interface under the recovery session and the session is recorded in the authentik event log for later review.
Fix the cause and clear the recovery path
Use the recovered session to correct the misconfigured stage, binding, or failed flow import that caused the lockout, and confirm a normal login works through the flow you repaired. Once the fix is verified, sign out of the recovery session and let the link expire or remove the access it granted, according to your version's behavior. Document the root cause, the change made and the time window used in the incident record. Done when a standard login succeeds, the recovery session has ended, and the incident record names the fix.
Remove residual copies of the link
Delete the recovery link from notes, clipboard managers and any chat or ticket where it may have been pasted, then clear the terminal scrollback on the operator workstation if the output was displayed there. Confirm with your team that the value was not forwarded. Rotate or review the akadmin credentials if the link may have been exposed beyond the intended operator. Done when no copy of the link remains outside the approved secure store and the review is noted in the incident record.
Docker Compose or Kubernetes: which command path fits your deployment
On a Docker Compose deployment, you run the recovery command from the host where the compose project lives, using the worker service. The worker runs background tasks and can execute the ak management command, so docker compose run against that service creates the recovery key without changing the running stack. Work from the directory that contains your compose file and its .env file, because Compose reads both from the project folder and the project name and variables must match the stack you are fixing.
- Locate the project directory: Change into the folder with the compose file and
.env. Running from a different folder can start a second, empty project. - Confirm the service name: List services with
docker compose psand confirm the worker service is present and running under the expected name in your file. - Run the documented form: Use
docker compose runagainst the worker service withak create_recovery_keyand theakadminuser, as the login troubleshooting documentation describes. - Set the duration in minutes: Since 2025.10 the duration argument is in minutes, not years, so confirm the value before you run the command.
- Protect the output: The command prints a link that grants direct access to the admin account, so share it only through a channel you control.
Before you run anything, check that the worker and PostgreSQL containers are healthy, because a stopped database makes the command fail in ways that look like a login problem.
On Kubernetes, the Helm chart runs the worker as its own deployment, so you use kubectl exec against a worker pod rather than a compose service. Choosing the wrong namespace or release is the most common reason the command appears to fail, because you may be looking at a staging or older install. Identify the namespace and release that serve your production login endpoint before you open a shell.
- Identify the namespace and release: Use
helm listacross namespaces to find the authentik release that serves your login URL, then note its namespace. - Find a worker pod: List pods with
kubectl get podsin that namespace and select a worker pod, not a server pod, by its name or label. - Confirm the pod is ready: Check that the pod shows Running with all containers ready before exec. A pod that is restarting may not accept the command.
- Run the command with exec: Use
kubectl execagainst the chosen worker pod withak create_recovery_keyandakadmin, with the duration in minutes. - Check the cluster context: Confirm your kubeconfig points to the intended cluster, since the same namespace name can exist in several clusters.
If no worker pod is ready, fix that first, because the recovery command depends on a running worker and a reachable database.
The two paths differ mainly in how you locate the running container, not in what the command does. Use the path that matches how your instance was installed, and confirm that choice against your own records rather than guessing from the hostname. A mismatch between the install method and the command path usually shows up as a missing service or pod, which is a sign to stop and verify rather than try alternatives on production.
- Match the install method: Docker Compose installs have a compose file on a host, while Helm installs have a release visible to
helm list. - Keep one source of truth: Record the compose project directory or the Helm release and namespace in your runbook before an incident.
- Avoid parallel stacks: Running a test stack with the same names can send your command to the wrong instance.
- Plan for a broken worker: If the worker cannot start, recovery through the command is not available, so the database and logs become the next checks.
- Ask your installer: If your deployment was built by a partner or internal team, confirm the exact service, release and namespace names they used.
The method you choose is only half the check, so confirm that the server still serves the login page before you treat the command as the fix.
Protecting the recovery link while it is valid
A recovery key gives direct admin access to anyone who holds the link, so its safety depends on how it is generated, shared, logged and allowed to expire. The cards below cover the main exposure points and the controls that limit each one while the window is open.
Treat the link as a password
Anyone who opens the recovery link gets direct access to the admin account, without needing the akadmin password or a second factor. The link should be handled like a live credential from the moment it is generated. Check that the people who will receive it know that opening it, forwarding it or copying it into another system counts as sharing admin access.
Keep the window short
Since authentik 2025.10 the duration passed to ak create_recovery_key is set in minutes, not years, so the window can be matched to the repair task. Generate the key close to when the fix will start, and choose the shortest duration that covers the work. Confirm the exact argument format for your version before you run it in production.
Share through a controlled channel
Links pasted into chat threads, tickets, email or shared documents persist long after the repair and can be read by people who never needed admin access. Send the link only to the one engineer doing the repair, through a channel your incident process already protects. Avoid putting it in a ticket that many people can read or in a screenshot.
Limit who can run the command
Running create_recovery_key requires access to the authentik worker container in Docker Compose or the worker pod in Kubernetes, which is effectively control of the deployment. Restrict that access to a named, small group, and confirm that the people with docker compose run or kubectl exec rights are the same people authorized to handle admin recovery.
Watch browser history and logs
The link can be captured by browser history on shared workstations, by proxy or load balancer access logs, and by terminal scrollback or shell history on the host. Open the link in a private session on a trusted machine, clear it from the history where practical, and check whether your logging pipeline records full request URLs before the key is generated.
Record the event and close the window
Note who generated the key, when, the duration chosen and who used it, in your change or incident record. Confirm how audit events for the recovery login reach your SIEM or log store. The documented way to end access is to let the window expire, so verify the time has passed, and rotate the akadmin password if the link may have been exposed.
Fixing the cause so the lockout does not return
A recovery key restores access but does not repair the flow, stage or policy that caused the lockout. Until the faulty configuration is fixed, the next admin session or the next login attempt will hit the same error. Start by identifying the last change that touched the sign-in path: a stage binding, a policy attached to a flow, an imported flow blueprint or a default flow that was edited. Compare the current state with the last known good state, either from your configuration history or from the blueprint file that was applied. Then revert or correct that single change, not the whole flow, so you can confirm which edit caused the failure.
Before you close the recovery window, test sign-in with a non-admin account that goes through the same flow the lockout affected. Use a separate browser session or a private window so you are not relying on the admin session you opened with the recovery link. Confirm that the login, any MFA step and the redirect back to the application all complete. Once a standard user can sign in, sign in as akadmin with the normal credentials, then rotate that password and check that any other admin accounts still work. Let the recovery key expire or confirm it is no longer usable, and remove any copies of the link you made during the incident.
Record each configuration change in version-controlled blueprints or another change log, with the author, the reason and the test that passed, so that the next edit to a sign-in flow can be reviewed and rolled back. Confirm with your own change process which tool or repository holds the authoritative copy of your flows, since a change made only in the admin interface may be overwritten by a later blueprint import. Review the authentik login troubleshooting documentation when you are writing the runbook entry so the recovery steps match the version you run.
Recovery options compared for different lockout causes
This table compares the four ways to regain control of authentik after a lockout, from a recovery key to escalation. Read each row against the cause of your lockout: the recovery key only restores admin access, while restoring a backup or editing configuration changes what the instance holds, so confirm the cause before you pick a path.
| Recovery option | When it fits | What it changes | What to confirm first |
|---|---|---|---|
| Recovery key via the worker | Admin cannot sign in after a misconfigured stage or a failed flow import, and the rest of the instance is intact | Creates a time-limited link for the akadmin account; the broken flow or stage stays as it is until you fix it | Which container runs the command (worker), that the key duration is set in minutes, and who can reach the link during its validity |
| Restoring a database backup | Data was corrupted, deleted or changed by a bad migration, and the recovery key cannot reach the cause | Rolls PostgreSQL back to the backup point, so changes made after that point are lost | Backup age, whether the backup covers the /data, /certs, /custom-templates and /blueprints directories, and the matching authentik version |
| Editing configuration through blueprints | A flow, stage or policy was changed in a way that breaks sign-in, and the change is tracked as a blueprint or in config files | Reapplies known-good objects or corrects settings on the next blueprint run | Whether the blueprint is in version control, the authentik version it targets, and whether a recovery key session is needed to apply it |
| Escalating to a vendor or partner | The cause is unclear, the instance is multi-tenant or customized, or the outage affects regulated services | Nothing is changed until an agreed diagnosis and written scope exist | Your support entitlement, which edition you run, and the logs and config exports to share without exposing secrets |
Security and audit considerations for emergency access
A recovery key bypasses the normal login path, so it needs the same scrutiny as any privileged action. The cards below cover who may create one, how each use is recorded, how duties are split when one person caused the failure, and how the event flows into the incident record.
Limit who can create recovery keys
Creating a recovery key requires shell access to the worker container or pod, which means access to the host, the Compose project or the Kubernetes cluster. Treat that access as the authority to create an admin session. Name the small group allowed to run ak create_recovery_key in your runbook, and confirm that cluster and host access for that group is reviewed on the same schedule as other privileged accounts.
Keep the duration short
Since authentik 2025.10 the lifetime passed to ak create_recovery_key is set in minutes rather than years, so a forgotten link expires on its own. Set the shortest window that still lets the restoring engineer finish the fix. Confirm in your own test environment that the link stops working after the window closes, and record the window you chose in the incident note.
Log and review every use
Anyone holding the link gets direct admin access, so each generation and each use should be traceable. Capture who ran the command, when, from which host or cluster, and which account the link was issued for. Ask your vendor or your own testing which of those details appear in container logs and which appear in authentik's event log, because the answer determines where your review query must look.
Separate the breaker from the restorer
The engineer who imported the broken flow or misconfigured the stage is often the one who is locked out and needs the key. Where staffing allows, have a second person with cluster or host access run the command and review the resulting changes. Illustrative example: one engineer edits the authorization stage, a second generates the key, and the first engineer repairs the flow while the second watches the admin session.
Feed the recovery into the incident record
Treat each recovery as a security event, even when the cause was an honest mistake. Open or update an incident ticket before the key is generated, attach the command history and the time window, and list every configuration change made during the session. Route the incident to the same owner who reviews failed logins and configuration changes, so a recovery is not closed without a review of what the admin account did.
Confirm what your edition records
Enhanced audit logging is one of the enterprise-only features listed on the authentik pricing page, alongside other audit-related items. Do not assume the open-source edition keeps the same depth of records. Ask your implementation partner or authentik to confirm which events are written, how long they are kept locally, and whether they can be forwarded to your SIEM before you rely on them for an emergency-access review.
Questions teams ask about authentik recovery keys
Is an authentik recovery key a permanent way to log in?
No. A recovery key is a temporary emergency access method that gives direct access to the admin account for a limited window, and it is meant for getting back into a broken instance, not for daily sign-in. Anyone who holds the generated link can use it during that window, so treat it as a credential. Once you have regained access, fix the underlying flow, policy or stage that caused the lockout, then confirm normal admin login works with your own accounts before the recovery window closes. Keep the key out of tickets, chat channels and shared logs.
How long does an authentik recovery key stay valid since 2025.10?
Since authentik 2025.10, the duration you pass to the ak create_recovery_key command is measured in minutes, not years, according to the authentik 2025.10 release notes. Earlier versions accepted longer durations, so scripts or runbooks written for older releases may set a window you did not intend. Check the release notes for your running version before you copy an old command, and confirm the exact argument format in the troubleshooting documentation for your deployment. Choose the shortest window that covers the repair work so the exposure stays small.
Can our own team recover admin access without outside help?
Usually yes, if you have shell or container access to the authentik server or worker and someone who can run commands in Docker Compose or kubectl exec. The recovery step itself is a single documented command. The harder part is diagnosing why the lockout happened, such as a misconfigured authentication stage, a failed blueprint import or a policy that blocks every login path. Teams that have tested this procedure before, and who keep their configuration in version control, tend to recover faster. Teams without that access or experience should plan for a partner or an internal platform owner to take the work.
What effort does a lockout recovery need from our team?
Effort depends on how much of the cause you can see. The minimum is someone with privileged access to the host or cluster, time to generate the link, and an admin who can complete the login through a private browser session. Beyond that, the work includes reviewing recent flow, stage and policy changes, checking the server and worker logs for the failing step, testing the fix in a non-production copy where possible, and recording what happened. Ask any partner for a written scope that separates the emergency access step from the root-cause fix and the post-incident hardening, so each part can be priced and scheduled on its own.
When should we bring in outside help for an authentik lockout?
Bring in help when the admin login path is down and nobody on your team can safely produce a recovery link, when the lockout affects several applications that depend on authentik for sign-in, or when the change that caused it is unclear. Outside help is also useful when the instance holds regulated data and you need a documented, reviewed procedure with evidence of what changed. A written scope agreed before work starts makes the engagement easier to control, and it keeps access to your environment limited to the systems the fix requires.
What drives the effort of recovering authentik access up or down?
The main drivers are the deployment model, the cause of the lockout, and how well the environment is documented. Docker Compose and Kubernetes differ in how you reach the worker and where logs live. A broken flow that is still in version control can be reverted quickly, while a change made directly in the admin interface on a single instance may need careful reconstruction. Other drivers include the number of applications that depend on the affected flow, whether a second administrator exists, the state of your backups, and whether your change process records who edited which stage or policy and when.
Does a recovery key replace a tested authentik backup?
No. A recovery key only restores admin sign-in to a running instance. It does not restore lost data, a corrupted PostgreSQL database, deleted users or applications, or uploaded files and certificates. If the database or the data directories are damaged, the key cannot fix them, and you need a restore from a backup that was tested before the incident. Your backup scope should cover the PostgreSQL database and the directories authentik uses for data, certificates, templates and blueprints. Confirm the exact list and restore order in the backup guidance for your version before you rely on it.
How DeployOpen scopes an authentik lockout recovery
A lockout engagement starts with a read-only review of what changed, not with a recovery key. DeployOpen asks for the authentik version in use, how it was deployed (Docker Compose or Helm on Kubernetes), whether PostgreSQL is bundled or managed separately, and the export or history of the last flow, stage, policy and blueprint changes. The goal is to identify the change that broke the login path: a stage bound to the wrong flow, a policy that now rejects every administrator, a failed flow import, or a branding or domain change. Recovery steps depend on that finding, so this review is the first deliverable and it shapes the rest of the scope.
Once the cause is known, the plan covers two separate tasks. The first is regaining access: creating a short-lived recovery key for akadmin with ak create_recovery_key on the worker, and limiting who can see the resulting link while it is valid. The second is the fix itself, such as restoring a flow from a known good export, correcting the binding, and testing login with a non-administrator account before the key expires. The plan should also name who holds the link, which channel it is shared through, and who confirms that the key was used and has lapsed. Confirm with your own team which of these steps need change approval under your own process.
Engagements are fixed-scope. The written scope lists the systems in review, the access that will be used, the steps DeployOpen will perform, the documentation delivered (a timeline of changes, the commands run, the verification results and follow-up hardening items) and what stays with your team. Most engagements are fixed-scope with deliverables and timelines agreed in writing before work starts, and a quote follows from that written scope. Ask for the scope to state who approves each step, where the record is kept, and whether ongoing support is needed afterward.
How DeployOpen delivers and supports authentik operations
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including authentik. For recovery work, we start by confirming how your admin access is lost, what the fix must change, and how the recovery link will be handled, so the emergency fix leaves a documented, tested path behind.
How we scope
- Written scope names the authentik deployment method, Docker Compose or Kubernetes, and the namespace or container names used for recovery commands.
- The scope records which flow, stage or policy caused the lockout and which admin accounts must regain access.
- Scope states who may hold the recovery link, how it is delivered, and the time window agreed for its use.
How we build
- We confirm the running version and the supported release line before running any recovery command in your environment.
- Recovery steps are run on the worker container with ak create_recovery_key, using a duration set in minutes as authentik 2025.10 requires.
- We correct the broken flow or configuration in a test copy first, then apply the change and verify login paths for each affected user group.
How we hand over
- You receive a written record of the cause, the commands run, the time each recovery link was valid, and the changes made.
- Runbook steps cover creating a recovery key, revoking access and reviewing audit events after a recovery.
- Handover includes a test of the corrected flow, so your team can rehearse recovery without touching production users.
How we support
- Fixed-scope engagements close with agreed deliverables, and follow-up items are listed in writing.
- Ongoing support, upgrades and continuous testing are available as a retainer if your team wants a partner on call.
- Before any authentik upgrade, we check release notes and the supported version list so recovery steps remain valid.
