Delete a user (admin)

Delete a user from the project. By default this is a hard delete — the row in auth.users is removed and any cascading deletes you've set up in your schema will fire. Pass should_soft_delete: true to instead anonymize the user and keep the row.

Service-role key required

This endpoint requires the project's service_role key. Never call it from a browser, mobile app, or any client you don't fully control.

Signature

supabase.auth.admin.delete_user(uid, should_soft_delete: false)

uid is positional; should_soft_delete is a real Ruby keyword argument. Raises ArgumentError synchronously if uid isn't a syntactically valid UUID.

Parameters

Name	Type	Required	Description
`uid`	String	Required	The user's UUID. Must be a syntactically valid UUID v4.
`should_soft_delete`	Boolean	Optional	When true, anonymize the user (clear email, phone, passwords, identities) but keep the row in auth.users so foreign-key references to the user.id remain valid. Defaults to false (hard delete).

Returns

nil

Returns nil on success. Raises Supabase::Auth::Errors::AuthApiError (status 404) if no user with that UUID exists; raises ArgumentError synchronously if uid isn't a valid UUID.

Example — hard delete

supabase.auth.admin.delete_user("8d7f5c4b-1234-4abc-9def-1234567890ab")

# The row is gone. Any ON DELETE CASCADE foreign keys to auth.users(id)
# will fire — make sure your schema is ready for that before calling.

Example — soft delete (preserve the row)

supabase.auth.admin.delete_user(
  "8d7f5c4b-1234-4abc-9def-1234567890ab",
  should_soft_delete: true
)

# The row is still present in auth.users — email/phone/identities are wiped,
# but foreign keys pointing at this user.id remain valid. Useful when you have
# audit logs or content rows you don't want to delete.

Example — handle missing user

begin
  supabase.auth.admin.delete_user(user_id)
rescue Supabase::Auth::Errors::AuthApiError => e
  warn "delete failed: #{e.status} #{e.message}"
end

Validates the UUID client-side via Helpers.is_valid_uuid and raises ArgumentError before any HTTP round-trip.