Retrieve a user (admin)
Fetch a single user by their UUID via the admin API.
Look up a single user by their UUID. Unlike get_user (which decodes the current bearer's JWT to find the user), this method fetches any user in the project — no session required.
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.get_user_by_id(uid)uid is a positional String — the user's UUID. Raises ArgumentError synchronously (before any HTTP call) if the string isn't a syntactically valid UUID.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
uid | String | Required | The user's UUID (the value of user.id). Must match the UUID v4 format /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i. |
Returns
A Struct with a single :user field carrying the full Types::User (id, email, phone, app_metadata, user_metadata, identities, factors, timestamps). Raises Supabase::Auth::Errors::AuthApiError with status 404 if no user with that UUID exists; raises ArgumentError synchronously if uid isn't a valid UUID.
Example — basic fetch
response = supabase.auth.admin.get_user_by_id("8d7f5c4b-1234-4abc-9def-1234567890ab")
response.user.email # => "ada@example.com"
response.user.app_metadata # => { "plan" => "pro", ... }
response.user.identities # => Array<Types::Identity>Example — handling not-found vs malformed UUID
begin
supabase.auth.admin.get_user_by_id("not-a-uuid")
rescue ArgumentError => e
# Validation is client-side, no HTTP round-trip happened.
warn "bad uuid: #{e.message}"
end
begin
supabase.auth.admin.get_user_by_id("00000000-0000-0000-0000-000000000000")
rescue Supabase::Auth::Errors::AuthApiError => e
warn "no such user: #{e.status} #{e.message}" # => 404
endPerforms a synchronous client-side UUID format check via Helpers.is_valid_uuid and raises ArgumentError before any HTTP call.