Invites and email

An admin invites a user by email and gives the user one or more roles. The routes are under /api/_pluto/supabase/access/**. Every write needs an admin. This needs the migration 008_users_and_roles_admin.sql, which the admin applies from /admin/migrations.

Before you invite

Invites need no setup. Check one thing: in the Supabase dashboard (Authentication, URL Configuration), the Site URL is the URL of your site.

Supabase accepts every link back to that host, so /admin/accept-invite needs no entry in the Redirect URLs. Add a Redirect URL only for another host, for example a preview deploy, or www. next to the bare domain.

How the email goes out

Without the service role key (the default). The server sends a passwordless sign-in link with the public key. Supabase creates the account and uses its sign-up or magic link email template. Public sign-up must be on, which is the Supabase default. Supabase sends one email per address every 60 seconds.

With the service role key (optional). Set NUXT_SUPABASE_SECRET_KEY to the Supabase secret key, in the environment of the running server. Never put it in the build environment. The server then uses the invite API of Supabase and the "Invite user" email template. This also works when public sign-up is off.

A custom invite template

A custom template makes the link work in every browser, because the page then reads a token_hash and not tokens in the URL hash. In the Supabase dashboard, open Authentication, Email Templates, Invite user. Use this link:

{{ .SiteURL }}/admin/accept-invite?token_hash={{ .TokenHash }}&type=invite

Custom SMTP

The built-in Supabase mailer sends very few emails. It sends only to members of your Supabase organization. To invite any other address, set up custom SMTP in Project Settings, Authentication, SMTP. A production site needs it anyway, for every auth email. Without it, an invite to another address answers 400 with the hint emailNotAuthorized.

What the invited user does

The user opens the link, sets a password on /admin/accept-invite, and goes to the admin.

An invite to an email that already has an account adds the roles and sends no email. The server never deletes an existing account.

Invites through Pluto mail

With the service role key and a working Pluto mail driver, an invite does not use the mailer of Supabase. The server makes a one-time link with auth.admin.generateLink, and Pluto mail sends the email. This lifts the team-only address rule and the Supabase email rate limit for invites.

Set the mail variables in the environment of the running server:

NUXT_SUPABASE_SECRET_KEY=
NUXT_PLUTO_MAIL_RESEND_API_KEY=re_...
NUXT_PLUTO_MAIL_FROM="Your Site <hello@your-domain.com>"

Settings, Email in the admin guides the setup. See Mail for every NUXT_PLUTO_MAIL_* variable.

If the send fails, the user and the roles stay. The admin gets the invite link to send by hand.

The link has this form:

<origin>/admin/accept-invite?token_hash=<hashed_token>&type=<type>

The link works once and expires.

Copy the invite link

With the service role key, an admin can copy the invite link. Use the row menu of the Users page, or the invite form. POST /api/_pluto/supabase/access/users/invite-link returns { status, link } and sends no email.

The locale field

The invite and resend routes take an optional locale. It must be one of the admin locales, or the answer is 400.

Invite errors

The invite modal handles these causes with an alert, Copy invite link (only when the server has the service key), and Set up email:

• emailNotAuthorized
• emailRateLimited
• emailInvalid

Without the service key, a hint says to set NUXT_SUPABASE_SECRET_KEY. Other errors show a toast.

Sign-up, reset, and magic link emails

These emails still come from Supabase. The Email tab in the settings has a guide panel for them. The panel says that Supabase sends them only to your Supabase team, and only a few each hour, without custom SMTP.

The panel shows the manual SMTP values for Resend, each with a copy button:

It also links to the Resend integration for Supabase, to the Supabase dashboard (best effort), and says to raise the email rate limit after you set custom SMTP. The panel never shows or stores a key.