From 2a748bb2107f0cee90faf711b5fdfc541e659704 Mon Sep 17 00:00:00 2001
From: Bruno Mercier Costa <94469565+emrcbrn@users.noreply.github.com>
Date: Mon, 12 Oct 2026 14:15:27 +0200
Subject: [PATCH] docs: describe the Waiting for Approval screen for pending
users (#1031)
* docs: describe the Waiting for Approval screen for pending users
The dashboard now shows pending users a dedicated Waiting for Approval
screen (dashboard #802) that names the account owner's masked email
(management #7533), replacing the old error page. Update the account
access troubleshooting page to match, and point pending users from the
admin-facing approve-users page to it.
* docs: note the owner address only shows when NetBird can resolve it
---
.../help/troubleshooting-account-access.mdx | 30 +++++++++++++++----
src/pages/manage/team/approve-users.mdx | 6 ++++
2 files changed, 30 insertions(+), 6 deletions(-)
diff --git a/src/pages/help/troubleshooting-account-access.mdx b/src/pages/help/troubleshooting-account-access.mdx
index 33cd5fa4..bfd22280 100644
--- a/src/pages/help/troubleshooting-account-access.mdx
+++ b/src/pages/help/troubleshooting-account-access.mdx
@@ -1,10 +1,23 @@
import {Note} from "@/components/mdx";
-export const description = "Why your NetBird user might be pending approval, or added to an account you don't recognize, and how to resolve it safely."
+export const description = "Why NetBird shows you a Waiting for Approval screen, or adds you to an account you don't recognize, and how to resolve it safely."
# Pending approval and account invitations
-Signed in and found your user **pending approval**, or landed in a NetBird account you don't recognize? This usually is not a bug. It almost always means you were added to an existing organization automatically, and an admin still has to approve you.
+Signed in to NetBird and landed on a **Waiting for Approval** screen, or in a NetBird account you don't recognize? This usually is not a bug. It almost always means you were added to an existing organization automatically, and someone in that organization still has to approve you.
+
+## What the Waiting for Approval screen tells you
+
+After you sign in, the dashboard shows three steps: **Account Created**, **Waiting for Approval**, and **Join Account**. Your user exists, but the account requires new users to be approved before they can use it, so you are held at the second step until someone approves you.
+
+Below the steps, the screen names the owner of the account you are waiting to join, for example `li****g@example.com`. Most of the part before the `@` is hidden to protect the owner's privacy, but the domain is shown in full. That domain is the quickest way to tell which organization you are waiting on.
+
+If the screen only says "Ask the owner of the account to approve your access", with no address, NetBird could not look up the owner's email. Everything below still applies.
+
+The screen has two buttons:
+
+- **Refresh** checks again whether you have been approved. Use it once someone tells you they approved you.
+- **Log Out** signs you out. Use it if you signed in with the wrong account, or you don't want to join this one.
## Why this happens
@@ -12,13 +25,18 @@ NetBird can add people to an account without a manual, one-by-one invite:
- **Indirect (domain) invites.** If an account has verified your email domain, new sign-ups with that domain join it automatically. See [Indirect user invites](/manage/team/add-users-to-your-network#indirect-user-invites).
- **Identity provider sync.** If your organization connects NetBird to its identity provider, being added to a synced group in the IdP provisions your user in NetBird. See [Provision users and groups from your identity provider](/manage/team/idp-sync).
-- **Approval is required.** When an account turns on [user approval](/manage/team/approve-users#require-user-approval), new users stay blocked until an admin approves them. That block is the "pending approval" state you see.
+- **Approval is required.** When an account turns on [user approval](/manage/team/approve-users#require-user-approval), new users stay blocked until an admin approves them. That block is the Waiting for Approval screen you see.
## What to do
-1. **Confirm it is your organization.** Check with your IT or security team whether they run NetBird and expect you on it. The account [Owner](/manage/team/user-roles#owner), of which there is exactly one per account, or an admin can confirm and approve you.
-2. **Ask an admin to approve your user.** Approval happens in the dashboard from the account's user list. See [Approve or reject user](/manage/team/approve-users#approve-or-reject-user).
-3. **If something looks off,** for example you don't recognize the account, your domain was claimed unexpectedly, or no one internally owns it, do not approve or accept anything. Treat it as suspicious and verify internally first.
+1. **Check the domain on the screen.** It is normally your organization's email domain. Confirm with your IT or security team that they run NetBird and expect you on it.
+2. **Ask the owner or an admin to approve you.** The screen names the account [Owner](/manage/team/user-roles#owner), of which there is exactly one per account, but any admin can approve you as well. They do it from the dashboard's user list. See [Approve or reject user](/manage/team/approve-users#approve-or-reject-user).
+3. **Click Refresh once you are approved.** The screen moves you into the account. If it still shows Waiting for Approval, your browser may be holding on to a cached session: open the dashboard in a private browser window and sign in again.
+4. **If something looks off,** for example the domain is not your organization's, you don't recognize the account, or no one internally owns it, do not ask anyone to approve you. Click **Log Out**, treat it as suspicious, and verify internally first.
+
+
+On self-hosted NetBird, the Waiting for Approval screen needs dashboard v2.93.0 or later, and the owner's address on it needs management v0.80.0 or later. Older dashboards show a **User Approval Pending** error page with only a **Sign Out** button instead: the steps above still apply, but after you are approved, sign out and sign in again.
+
Still unsure who owns the account, or think you were added to the wrong one? Reach out through [NetBird Support](/help/netbird-support) and the team can help confirm the account and its owner.
diff --git a/src/pages/manage/team/approve-users.mdx b/src/pages/manage/team/approve-users.mdx
index e96ed584..ad9f3952 100644
--- a/src/pages/manage/team/approve-users.mdx
+++ b/src/pages/manage/team/approve-users.mdx
@@ -4,6 +4,10 @@ import {Note} from "@/components/mdx";
The user approval feature enhances security by requiring manual administrator approval before a user can join your NetBird organization via domain matching.
New NetBird Cloud accounts have user approval enabled by default.
+
+Signed in and waiting for approval yourself? See [Pending approval and account invitations](/help/troubleshooting-account-access) for what the Waiting for Approval screen means and what to do next.
+
+
## Require user approval
Navigate to the Dashboard's `Settings` page and the `Authentication` tab and enable or disable `User Approval Required`.
@@ -17,6 +21,8 @@ Navigate to the Dashboard's `Settings` page and the `Authentication` tab and ena
## Approve or reject user
To approve a user, navigate to the [Users Page](https://app.netbird.io/team/users) and click the `Approve` or `Reject` button on the right side of the users table.
+While they wait, the user sees a **Waiting for Approval** screen that names the account owner's email address, partly hidden, when NetBird can look it up. Otherwise it just asks them to contact the account owner. Any admin can approve them, not only the owner. Once approved, the user clicks **Refresh** on that screen to join the account.
+
