Getting admin access
How an admin signs in, how the worker verifies the token, and how the admin_users table, the ADMIN_EMAILS seed floor and the protection guards decide who gets in.
Last updated 2026-08-06
Summary#
Admin access is decided in two places: Supabase proves who you are, and the D1 table admin_users decides whether that identity is staff and what role it has. The address is not the credential. An admin_users row grants its role only once it is bound to one specific Supabase user id, so registering or controlling an email address that appears in the source or the documentation grants nothing. This page walks the whole chain, names every guard, and gives the exact steps to grant a new admin.
Purpose#
Staff need to be added and removed without a code deploy, which means the list lives in the database rather than in the source.
The second property is newer and it is the important one. An email address must never be enough on its own. Supabase will register anybody for any address that is not already taken, so for as long as the decision rested on the address in the token, anyone who could read an admin address could claim the account and inherit its role. The console's own page and this documentation both named one. So admin_users now records the Supabase user id a row belongs to, and the role is granted only to that id.
This replaced a "fail-safe floor" that granted owner from a hardcoded address list whenever D1 could not be read. That floor protected nothing real: every admin screen needs D1, so it handed out ownership exactly when the console was unusable anyway.
Requirements#
Before an address can sign in as an admin, all of the following must be true.
| Requirement | Detail |
|---|---|
| A Supabase auth user exists for the address | Project cnjycxhmnepvqsuyrwem by default, overridable with SUPABASE_URL |
| The email is confirmed | The worker accepts the identity only when email_confirmed_at or confirmed_at is set on the Supabase user |
| The address is staff | An admin_users row with status = 'active'. There is no longer any path that grants a role without a row. |
| The row is bound to your account | The row's user_id must be the Supabase user id in your token. An unbound row binds itself on the first sign-in by an account created before 28 September 2026; after that only an id listed in MV_ADMIN_IDS may bind. |
MONITOR_DB is bound | Needed for admin_users and for every screen. Unbound throws MONITOR_DB not bound. Wrangler may need a redeploy. and no admin can sign in. |
The address is always compared lower-cased.
Permissions#
There are two roles. Both see every screen. The difference is mutation rights.
| Capability | admin | owner |
|---|---|---|
| Load any screen and every read endpoint | Yes | Yes |
Resolve or reopen an error issue (/api/admin/errors/resolve) | Yes | Yes |
Resolve a workflow failure (/api/workflow/failure/resolve) | Yes | Yes |
| Add, suspend, promote, demote or remove an admin | No | Yes |
| Set or delete a configuration key | No | Yes |
| Change a cache lifetime, apply to all, clear the cache | No | Yes |
| Run a background job now | No | Yes |
| Set a plan, reset usage, refund, suspend, reactivate, remove a seat | No | Yes |
| Disconnect a customer's social channel | No | Yes |
| Moderate a customer blog post | No | Yes |
Owner-only endpoints reply 403 with a specific message, for example {"error":"Only an owner can manage admins."} or {"error":"Only an owner can change config."}. The UI mirrors the same split by keeping the owner-only cards (#adminsAddCard, #configEditCard, #maintenanceCard, #recoCard, #tcOwnerCard) hidden until /api/admin/me reports role: "owner". The hiding is convenience, not the control. The server check is the control.
Note: No admin endpoint is rate limited. The only 429 responses in the worker are customer quota gates.
Navigation Path#
https://metricvaultai.com/admin.html
The page is a plain static asset. The worker has no route for /admin or /admin.html, so there is no server-side redirect and no gate on the HTML itself. Loading the page is not access. Every /api/admin/* call it makes is gated independently.
Step-by-Step Guide#
Grant access to a new admin#
- Ask an existing owner to open the console and select Admins in the Operations group of the sidebar.
- In the Add an admin card, type the address into the field labelled
name@example.com. - Choose a role from the select:
Adminfor read-only staff,Ownerfor full mutation rights. The select defaults toAdmin. - Press Add admin. A blank field returns the client message
Enter an email.A successful write showsDone.and the row appears in the Admin accounts table. - Have the new admin create a Supabase account for that exact address and confirm the email. Without the confirmation the worker will not accept the identity, even though the
admin_usersrow exists. - The new admin opens
/admin.html, enters the address and password, and presses Sign In.
Grant access without the console#
If nobody can sign in, add the address to the ADMIN_EMAILS environment variable on the Cloudflare Pages project as a comma-separated value and redeploy. That puts the address on the seed floor, which grants owner whenever admin_users has no row for it or D1 cannot be read. It is the recovery path, not the normal path.
Sign in#
- Open
/admin.html. The login card shows theMETRIC VAULTwordmark and the subtitleAdmin Dashboard. - Fill in
Email Address(placeholderEnter your email) andPassword(placeholderEnter your password). Sign-in is email and password only; Google OAuth was removed because the console is staff-only. - Press Sign In.
- The page calls
supabase.auth.signInWithPassword, then immediately POSTs{ token }to/api/admin/me. Only after that returns{ok:true}does the console render.
How the chain actually resolves#
mvResolveAdmin(token, env) in _worker.js is the single decision point. Every admin endpoint calls it, directly or through the mvVerifyAdmin wrapper, so no route can be left ungated by accident.
- No token, no access. A missing token returns
nullimmediately. The check fails closed at every stage. - Verify the token with Supabase. The worker fetches
<SUPABASE_URL>/auth/v1/userwithAuthorization: Bearer <token>and anapikeyheader. The apikey is taken fromenv.SUPABASE_ANON_KEY, thenenv.SUPABASE_SERVICE_KEY, then the anon key inlined in the worker. - Require a confirmed email and a user id. The identity is accepted only when the Supabase user has
email_confirmed_atorconfirmed_atand anid. The address is lower-cased. A network failure, a non-OK response, or a response carrying no id returnsnull. - Ask
admin_users. The worker ensures the schema exists, seeds the table if it is empty, then runsSELECT role, status, user_id FROM admin_users WHERE email = ?. No row means denied.statusother thanactivemeans denied. - Check the binding. This is the authorisation step.
- The row has a
user_idmatching the token's id: access granted. - The row has a
user_idthat does not match: denied, and the worker logs{"admin":"id-mismatch","email":"a***@..."}. The address now answers to a different Supabase account than the one the role was granted to. - The row has no
user_id: it binds to this account, but only if the account was created before 28 September 2026 or its id is listed inMV_ADMIN_IDS. Otherwise it is denied and logged as{"admin":"bind-refused",...,"reason":"account newer than cutover"}. - Stamp last seen. When a role is granted,
last_seen_atis updated toDate.now()in milliseconds. That is what the Admins table renders as a relative time.
The bootstrap list#
mvAdminSeedList(env) returns a short list of internal addresses concatenated with every entry in env.ADMIN_EMAILS split on commas, trimmed and lower-cased. The addresses are in _worker.js, which is server-side and never served.
It writes rows into admin_users exactly once, when that table is empty, as role='owner', status='active', added_by='seed' and unbound. Those rows authorise nobody until a sign-in binds one. The list is not consulted for any other purpose except the protection guards below.
Unlinking an account#
The Admins screen shows an Account column: linked when the row is bound, not linked when it is not. An owner sees an Unlink account button on any linked row, which clears the binding so the holder can bind a different Supabase account on their next sign-in. Use it when moving an admin to a new sign-in.
Unlinking does not weaken the boundary, because the cutover still applies: only an account that existed before 28 September 2026 can take a freshly unlinked row. For a genuinely new account, add its Supabase user id to MV_ADMIN_IDS instead. You cannot unlink the row you are currently signed in with.
The seed-owner guard#
Bootstrap addresses cannot be locked out through the console.
| Attempt on a bootstrap address | Result |
|---|---|
add with role admin | Role is forced to owner. The downgrade never lands. |
update that suspends or demotes | 400 {"error":"This is a protected owner account."} |
remove | 400 {"error":"This is a protected owner account."} |
The Admins list returns locked: true on those rows and the UI renders the literal word protected in place of the action buttons.
The self-action guard#
An owner cannot remove their own footing either.
| Attempt on your own address | Result |
|---|---|
update that suspends or demotes | 400 {"error":"You cannot suspend or demote your own account."} |
remove | 400 {"error":"You cannot remove your own account."} |
Promoting yourself is not blocked, because you must already be an owner to reach the endpoint at all.
Token transport and session handling#
The console reads session.access_token and sends it as a token field in the JSON body of every admin call. There is no Authorization header on these routes. supabase.auth.onAuthStateChange re-verifies on SIGNED_IN and signs out any identity that fails, and page load restores the session with getSession() before running the same server check.
One client behavior is worth knowing when you debug a lockout. /api/admin/me is the only thing that decides whether the console unlocks: a 403 shows You are not authorized to access this dashboard. and signs the session out, and any other failure, such as a 5xx or a network error, is also treated as "not an admin".
There used to be a fallback here that granted owner from a one-entry client list when that call failed. It was removed with the seed floor. The address it contained was readable by anyone who opened /admin.html, and the fallback only ever unlocked the page shell in front of endpoints that refused every call anyway.
Troubleshooting#
| Symptom | Likely cause | Fix |
|---|---|---|
You are not authorized to access this dashboard. after a correct password | /api/admin/me returned 403: no active admin_users row, or the row is bound to a different Supabase account, or it is unbound and this account is too new to bind | Have an owner add the address on the Admins screen; if the row exists but shows not linked and the account is new, add its Supabase user id to MV_ADMIN_IDS; if it is bound to an old account, an owner uses Unlink account |
Invalid email or password. | Supabase rejected the credentials | Reset the password, or confirm the address exists in the Supabase project |
An error occurred. Please try again. | The sign-in call threw before a verdict | Retry; if it persists, check that Supabase is reachable from the browser |
| Sign-in works but every screen is empty and the console logs 403s | The access token expired, or the Supabase user's email is not confirmed | Sign out and back in; confirm the email in Supabase |
| Screens load but no Save, Apply or Run buttons appear | The role is admin, not owner | An owner promotes the account with Make owner on the Admins screen |
MONITOR_DB not bound. Wrangler may need a redeploy. | The D1 binding is missing on the Pages project | Restore the binding and redeploy. Nobody can sign in as an admin until it is back, by design: the role lives in that database and there is no floor around it |
| The whole console 403s for everyone | admin_users was emptied or every row was suspended | Repair the table directly with wrangler d1. There is deliberately no address that resolves to owner without a row, so this cannot be fixed from the console |
Errors on the login card auto-hide after 5000 ms.
The Forgot password? link sends the reset email to whatever is typed in the email field, and the success message names that address: Password reset email sent to <address>. Check your inbox. Clicking it with the field empty asks you to fill it in first. It used to ignore the field and always mail one hardcoded address, which both published that address in the page source and meant the link could only ever help one person.
FAQs#
Do I need to redeploy after adding an admin? No. admin_users is read on every request, so a row added on the Admins screen takes effect on the new admin's next sign-in. Only ADMIN_EMAILS requires a redeploy, because it is an environment variable.
What is the difference between suspending an admin and removing one? Suspending sets status = 'suspended' and keeps the row. The row is authoritative, so the address is denied even if it is on the seed floor. Removing deletes the row, which drops the decision back to the seed floor: a seed address would then resolve to owner again. That is why removal of a seed address is blocked outright.
Can an admin escalate themselves to owner? No. /api/admin/users/mutate returns 403 {"error":"Only an owner can manage admins."} before it reads the action.
Does signing an admin out revoke their access immediately? Not entirely. Signing out revokes refresh tokens, but an already-issued Supabase access token stays valid until it expires. There is no force-logout endpoint on this Supabase version. See What the admin console cannot do yet.
Is the admin page itself protected by anything at the edge? Nothing in the repository configures Cloudflare Access or an edge rule for /admin.html, and _headers has no admin entry. Treat the per-endpoint token check as the only access control that is guaranteed to be in place.
Is admin activity logged? Every mutation is, with actor, action, target and a short meta string. Reads are not. See Audit log.
See also
Was this article helpful?
Thanks — feedback noted for the docs team.