Skip to content
Metric VaultHelp Center
Open app

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.

RequirementDetail
A Supabase auth user exists for the addressProject cnjycxhmnepvqsuyrwem by default, overridable with SUPABASE_URL
The email is confirmedThe worker accepts the identity only when email_confirmed_at or confirmed_at is set on the Supabase user
The address is staffAn 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 accountThe 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 boundNeeded 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.

Capabilityadminowner
Load any screen and every read endpointYesYes
Resolve or reopen an error issue (/api/admin/errors/resolve)YesYes
Resolve a workflow failure (/api/workflow/failure/resolve)YesYes
Add, suspend, promote, demote or remove an adminNoYes
Set or delete a configuration keyNoYes
Change a cache lifetime, apply to all, clear the cacheNoYes
Run a background job nowNoYes
Set a plan, reset usage, refund, suspend, reactivate, remove a seatNoYes
Disconnect a customer's social channelNoYes
Moderate a customer blog postNoYes

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

Note: No admin endpoint is rate limited. The only 429 responses in the worker are customer quota gates.

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#

  1. Ask an existing owner to open the console and select Admins in the Operations group of the sidebar.
  2. In the Add an admin card, type the address into the field labelled name@example.com.
  3. Choose a role from the select: Admin for read-only staff, Owner for full mutation rights. The select defaults to Admin.
  4. Press Add admin. A blank field returns the client message Enter an email. A successful write shows Done. and the row appears in the Admin accounts table.
  5. 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_users row exists.
  6. The new admin opens /admin.html, enters the address and password, and presses Sign In.
Screenshot
The Admins screen with the owner-only "Add an admin" card open and the Admin accounts table below it.

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#

  1. Open /admin.html. The login card shows the METRIC VAULT wordmark and the subtitle Admin Dashboard.
  2. Fill in Email Address (placeholder Enter your email) and Password (placeholder Enter your password). Sign-in is email and password only; Google OAuth was removed because the console is staff-only.
  3. Press Sign In.
  4. The page calls supabase.auth.signInWithPassword, then immediately POSTs { token } to /api/admin/me. Only after that returns {ok:true} does the console render.
Screenshot
The admin login card showing the METRIC VAULT wordmark, the Admin Dashboard subtitle, the two fields and the Sign In button.

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.

  1. No token, no access. A missing token returns null immediately. The check fails closed at every stage.
  2. Verify the token with Supabase. The worker fetches <SUPABASE_URL>/auth/v1/user with Authorization: Bearer <token> and an apikey header. The apikey is taken from env.SUPABASE_ANON_KEY, then env.SUPABASE_SERVICE_KEY, then the anon key inlined in the worker.
  3. Require a confirmed email and a user id. The identity is accepted only when the Supabase user has email_confirmed_at or confirmed_at and an id. The address is lower-cased. A network failure, a non-OK response, or a response carrying no id returns null.
  4. Ask admin_users. The worker ensures the schema exists, seeds the table if it is empty, then runs SELECT role, status, user_id FROM admin_users WHERE email = ?. No row means denied. status other than active means denied.
  5. Check the binding. This is the authorisation step.
    • The row has a user_id matching the token's id: access granted.
    • The row has a user_id that 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 in MV_ADMIN_IDS. Otherwise it is denied and logged as {"admin":"bind-refused",...,"reason":"account newer than cutover"}.
  6. Stamp last seen. When a role is granted, last_seen_at is updated to Date.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 addressResult
add with role adminRole is forced to owner. The downgrade never lands.
update that suspends or demotes400 {"error":"This is a protected owner account."}
remove400 {"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 addressResult
update that suspends or demotes400 {"error":"You cannot suspend or demote your own account."}
remove400 {"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#

SymptomLikely causeFix
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 bindHave 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 credentialsReset the password, or confirm the address exists in the Supabase project
An error occurred. Please try again.The sign-in call threw before a verdictRetry; if it persists, check that Supabase is reachable from the browser
Sign-in works but every screen is empty and the console logs 403sThe access token expired, or the Supabase user's email is not confirmedSign out and back in; confirm the email in Supabase
Screens load but no Save, Apply or Run buttons appearThe role is admin, not ownerAn 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 projectRestore 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 everyoneadmin_users was emptied or every row was suspendedRepair 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?