Supabase Auth admin API: service-role user management without the footguns

TL;DR

For user creation, prefer invites (inviteUserByEmail) over createUser when the user should set their own password. createUser with a password you chose is a credential you now own. Confirm the cascade behavior before deleting: check what on delete your FKs use, or you orphan rows across the schema.

Steps

1. Build a dedicated admin client with the service role key, used only in server code: Edge Functions, API routes, admin scripts. Never import it into frontend code.
2. For user creation, prefer invites (inviteUserByEmail) over createUser when the user should set their own password. createUser with a password you chose is a credential you now own.
3. Deleting a user is irreversible and cascades to their data per your foreign keys. Confirm the cascade behavior before deleting: check what on delete your FKs use, or you orphan rows across the schema.
4. Updating user metadata via the admin API bypasses the user's own update path. Log who did what and when; admin writes without an audit trail are indistinguishable from a breach.
5. Never expose admin operations through an unauthenticated endpoint. Every admin route must verify the caller is an admin (check a role claim with getClaims()), not just that they are logged in.

When to use

You are seeing this: Creating, updating, and deleting users programmatically goes through the admin API with the service role key. Use this skill when you run into "Supabase Auth admin API: service-role user management without the footguns".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/auth/managing-user-data