Send an email invite link (admin)

Send an invitation email to a new user. The email links to the configured redirect_to URL with an embedded invite token; clicking it creates the user and signs them in. Use this for B2B onboarding flows where you're seeding accounts from a known list of addresses.

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.invite_user_by_email(email, options = {})

email is a positional String; options is an optional positional hash (defaults to {}).

Parameters

Name	Type	Required	Description
`email`	String	Required	The address to invite. If a user with this email already exists, GoTrue responds with 422.
`options`	Hash	Optional	Optional invite-flow options — see keys below.

options keys

Name	Type	Required	Description
`data`	Hash	Optional	Seed user_metadata for the new user. Carried into the user row when the invite is accepted.
`redirect_to`	String	Optional	Where the invite-link should send the user after they click it. Must match an entry in your project's Auth → URL Configuration → Redirect URLs allowlist.

Returns

Supabase::Auth::Types::UserResponse

A Struct with a single :user field carrying the newly created (still-unconfirmed) Types::User. Raises Supabase::Auth::Errors::AuthApiError (status 422) if a user with the email already exists.

Example — minimal invite

response = supabase.auth.admin.invite_user_by_email("ada@example.com")

response.user.id              # => "8d7f5c4b-..."
response.user.email           # => "ada@example.com"
response.user.invited_at      # => 2026-06-12 12:34:56 UTC

Example — invite with seeded metadata and a redirect

supabase.auth.admin.invite_user_by_email(
  "ada@example.com",
  data: { display_name: "Ada Lovelace", role: "engineer", invited_by_team: "team_abc" },
  redirect_to: "https://app.example.com/onboarding"
)

Example — handle "already invited"

begin
  supabase.auth.admin.invite_user_by_email("existing@example.com")
rescue Supabase::Auth::Errors::AuthApiError => e
  # 422 — a user with this email already exists. Re-issue the invite via
  # admin.generate_link(type: "invite") if you want to send another email.
  warn "invite failed: #{e.status} #{e.message}"
end

options is a single positional hash, so callers write invite_user_by_email("...", data: { ... }, redirect_to: "...") via Ruby's hash-literal shorthand.