Authentication definition in Supabase Auth
Authentication means checking that a user is who they say they are.
Supabase · Auth · all subjects
authentication/concepts
93 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Standalone and integrated usage
Supabase Auth can be used as a standalone product or integrated with the Supabase ecosystem.
Passwordless login benefits
Passwordless login can improve user experience by not requiring users to create and remember a password, increase security by reducing the risk of password-related security breaches, and reduce support burden of dealing with password resets and other password-related flows.
Edit email templates in hosted projects
For hosted Supabase projects, edit email templates on the Email Templates page in the dashboard. The template builder uses the same terminology and variables documented in the Supabase auth guides.
Edit email templates locally and self-hosted
The dashboard template builder does not apply when running local development with CLI or self-hosted Supabase. Customize templates in supabase/config.toml and local HTML files instead. For self-hosted deployments, refer to the Custom email templates guide.
Management API for email templates
Email templates can be managed using the Management API. Use GET https://api.supabase.com/v1/projects/{PROJECT_REF}/config/auth with Authorization Bearer token to retrieve current email templates. Use PATCH https://api.supabase.com/v1/projects/{PROJECT_REF}/config/auth to update templates. The access token is obtained from https://supabase.com/dashboard/account/tokens.
Server-side rendering with email links
When using server-side rendering, the default email link redirects after verification to the redirect URL with the session in query fragments. To access the session on the server-side, customize the email link to redirect to a server-side endpoint. For example, use <a href="https://api.example.com/v1/authenticate?token_hash={{ .TokenHash }}&type=invite&redirect_to={{ .RedirectTo }}">. The server can then call verifyOtp with the token_hash and type to get an authenticated session in the response body before redirecting the user.
Email prefetching security issue
Email providers may have spam detection or security features that prefetch URL links from emails (e.g. Safe Links in Microsoft Defender for Office 365). This causes the {{ .ConfirmationURL }} to be consumed instantly, leading to a 'Token has expired or is invalid' error.
Email tracking breaks Supabase links
If an external email provider enables email tracking, the links inside Supabase email templates will be overwritten and won't perform as expected. It is recommended to disable email tracking to ensure email links function properly.
Conditional email template example
Email templates support conditional logic using Go Templates syntax. For example, send different emails based on user metadata: {{ if eq .Data.Domain "https://www.example.com" }} (content for main users) {{ else if eq .Data.Domain "https://www.earlyaccess.trial.com" }} (content for early access users) {{ end }}
Go Templates in email templates
Supabase Auth uses Go Templates for email templates, allowing conditional rendering of information based on template properties using if/else statements.
Email template configuration keys via Management API
Email templates via Management API use keys in format: mailer_subjects_{template_name} for subjects and mailer_templates_{template_name}_content for HTML content. Template names include: confirmation, magic_link, recovery, invite, reauthentication, email_change, password_changed_notification, email_changed_notification, phone_changed_notification, mfa_factor_enrolled_notification, mfa_factor_unenrolled_notification, identity_linked_notification, identity_unlinked_notification. Security notifications are enabled with mailer_notifications_{type}_enabled boolean flags.
Security notification email types
Supabase sends eight types of security notification emails: Password changed, Email address changed, Phone number changed, Sign-in method linked, Sign-in method removed, Verification method added, and Verification method removed. Security emails are only sent to users if the respective security notifications have been enabled at a project-level.
Email template variables
Email templates support the following variables: {{ .ConfirmationURL }} contains the confirmation URL for email verification; {{ .Token }} contains a 6-digit One-Time-Password (OTP); {{ .TokenHash }} contains a hashed version of the token useful for constructing custom email links; {{ .SiteURL }} contains the application's Site URL from authentication settings; {{ .RedirectTo }} contains the redirect URL passed when signUp, signInWithOtp, signInWithOAuth, resetPasswordForEmail, or inviteUserByEmail is called; {{ .Data }} contains metadata from auth.users.user_metadata for personalizing emails; {{ .Email }} contains the original email address (empty when linking email to anonymous user); {{ .NewEmail }} contains the new email address (only in Change email address template); {{ .OldEmail }} contains the old email address (only in Email address changed notification template); {{ .Phone }} contains the new phone number (only in Phone number changed notification template); {{ .OldPhone }} contains the old phone number (only in Phone number changed notification template); {{ .Provider }} contains the provider of the linked or removed sign-in method (only in Sign-in method linked and removed templates); {{ .FactorType }} contains the type of verification method added or removed (only in Verification method added and removed templates).
HTTP hook security: Standard Webhooks Specification
HTTP Hooks in Supabase follow the Standard Webhooks Specification, which attaches three security headers to guarantee payload integrity: webhook-id (the unique webhook identifier), webhook-timestamp (integer UNIX timestamp in seconds since epoch), and webhook-signature (generated from the body of the hook). When a request is made to the HTTP hook, you should use Standard Webhooks libraries to verify these headers.
Developing HTTP hooks locally with config.toml
To configure an HTTP hook locally, modify the auth.hook.<hook_name> field in config.toml and set uri to a valid HTTP URI. For example: [auth.hook.send_sms] enabled = true uri = "http://host.docker.internal:54321/functions/v1/send_sms" secrets = "env(SEND_SMS_HOOK_SECRETS)". Fill in the hook secret in supabase/functions/.env as SEND_SMS_HOOK_SECRETS='v1,whsec_<base64-secret>'. Start the function locally with supabase functions serve send-sms --no-verify-jwt to disable JWT verification since hooks may run before a JWT is issued. Payloads are sent uncompressed and there is a 20KB payload limit.
Developing Postgres function hooks locally with config.toml
To configure a Postgres function hook locally, modify the auth.hook.<hook_name> field in config.toml and set uri to pg-functions://postgres/<schema>/<function_name>. You must grant the supabase_auth_admin role permission to execute the hook and usage on the schema. You must revoke permissions from authenticated and anon roles. Save the auth hook as a migration using supabase migration new to version it and share with team members.
Auth hook signatures and return types
A Postgres function hook signature takes a single event parameter of type jsonb and returns jsonb. Example: create or replace function public.custom_access_token_hook(event jsonb) returns jsonb language plpgsql as $$...$$ The hook function name should correspond to one of the available hooks (e.g., send_sms, custom_access_token).
Hook error handling for Postgres hooks
Runtime errors should be returned as a JSON object with an error property containing http_code (number indicating the HTTP code to be returned; defaults to 500 if not set) and message (string, required). Example: {"error": {"http_code": 429, "message": "You can only verify a factor once every 10 seconds."}}. Errors returned from Postgres hooks are not retry-able. When an error is returned, it is propagated from the hook to Supabase Auth and translated into an HTTP error returned to your application.
Hook error handling for HTTP hooks status codes
HTTP hooks return status codes to determine next steps: 200, 202, 204 indicate a valid response and proceed with successful processing. 403, 400 are treated as Internal Server Errors and return a 500 error code. 429, 503 are retry-able errors for temporary server overload or maintenance. Note that 204 status is not supported by Custom Access Token, MFA Verification Attempt, and Password Verification Attempt hooks which require a response body.
HTTP hook retry behavior
On a retry-able error (429 or 503 status code), HTTP Hooks attempt up to three retries with a back-off of two seconds. The entire webhook invocation including all retry requests must complete within a 5 second time budget. Return a retry-able error by attaching an appropriate status code (429, 503) and a non-empty retry-after header. All responses, including error responses, need a Content-Type of application/json.
Auth hook timeout limits
Postgres Hooks have a timeout limit to complete processing (specific timeout value available in config). HTTP Hooks should complete in their specified timeout limit (specific timeout value available in config). Both HTTP and Postgres hooks are run in a transaction to limit the duration of execution and avoid delays in the authentication process.
Auth hook function naming conventions
Hook function names should follow suggested naming: send_sms for Send SMS hook, send_email for Send Email hook, custom_access_token for Custom Access Token hook, mfa_verification_attempt for MFA Verification Attempt hook, password_verification_attempt for Password Verification Attempt hook.
When each auth hook is called
Send SMS hook is called each time an SMS is sent and allows customization of message content and SMS provider. Send Email hook is called each time an email is sent and allows customization of message content and email provider. Custom Access Token hook is called each time a new JWT is created and returns the claims to be present in the JWT. MFA Verification Attempt hook is called each time a user tries to verify an MFA factor and returns a decision on whether to reject or allow the attempt. Password Verification Attempt hook is called each time a user tries to sign in with a password and returns a decision whether to allow or reject the attempt.
Postgres function hook security: supabase_auth_admin role permissions
When you configure a Postgres function as a hook, Supabase automatically grants execute permission to the supabase_auth_admin role (which is the Postgres role used by Supabase Auth to make database requests). You must grant usage on the schema to supabase_auth_admin. You should revoke execute permissions from authenticated, anon, and public roles to ensure the function is not accessible by Supabase Data APIs. You must alter row-level security policies to allow the supabase_auth_admin role to access tables that have RLS policies.
Postgres function hook security definer tag not recommended
Functions created via the Supabase dashboard with the security definer tag will take on the postgres role, which has extensive permissions making it easier for undesirable actions to occur. For security, Supabase recommends against using the security definer tag and instead explicitly granting permissions to supabase_auth_admin.
HTTP hook secret format
When an HTTP hook is created, the secret is generated in the format v1,whsec_<base64-secret> where v1 denotes the version of the hook, whsec_ signifies that the secret is symmetric, and <base64-secret> is a Standard Base64 encoded secret which can contain the characters +, /, and =. The secret is used to verify the payload received in your hook.
What is an auth hook
A hook is an endpoint that allows you to alter the default Supabase Auth flow at specific execution points. Developers can use hooks to add custom behavior that is not supported natively.
Auth hook use cases
Hooks help you track the origin of user signups by adding metadata, improve security by adding additional checks to password and multi-factor authentication, support legacy systems by integrating with identity credentials from external authentication systems, add additional custom claims to your JWT, and send authentication emails or SMS messages through a custom provider.
Available auth hooks and plan availability
Before User Created hook is available on Free and Pro plans. Custom Access Token hook is available on Free and Pro plans. Send SMS hook is available on Free and Pro plans. Send Email hook is available on Free and Pro plans. MFA Verification Attempt hook is available on Teams and Enterprise plans. Password Verification Attempt hook is available on Teams and Enterprise plans.
Two types of auth hooks: Postgres Function and HTTP Endpoint
A Postgres function can be configured as a hook by taking in a single argument of type JSONB (the event) and returning a JSONB object. The function runs on your database so the request does not leave your project instance. An HTTP Hook is an endpoint which takes in a JSON event payload and returns a JSON response. You can use any HTTP endpoint as a hook, including an endpoint in your application or a Supabase Edge Function.
Client layer locations and responsibilities
The client layer runs in your app and can run in frontend browser code, backend server code, or native applications. It provides functions to sign in and manage users. The client layer manages HTTP calls to the Supabase Auth backend, handles persistence and refresh of Auth tokens, integrates with other Supabase products, and can be implemented using Supabase client SDKs or custom HTTP client code.
Auth service responsibilities
The Auth service is an Auth API server written and maintained by Supabase, forked from the GoTrue project originally created by Netlify. The Auth service is responsible for validating, issuing, and refreshing JWTs. It serves as the intermediary between the app and Auth information in the database. It communicates with external providers for Social Login and SSO. When you deploy a new Supabase project, an instance of this server is deployed alongside your database and the database is injected with the required Auth schema.
Four major layers of Supabase Auth architecture
Supabase Auth has four major layers: the client layer, Envoy API gateway, Auth service, and Postgres database. The client layer can be Supabase client SDKs or manually made HTTP requests. The Envoy API gateway is shared between all Supabase products. The Auth service is the Auth API server. The Postgres database is shared between all Supabase products.
JavaScript AuthError class hierarchy
All errors originating from the supabase.auth namespace in JavaScript are wrapped by the AuthError class. Error objects are split into AuthApiError (errors from Supabase Auth API) and CustomAuthError (errors from client library state). Use isAuthApiError() instead of instanceof checks to identify AuthApiError types. Use the name property to identify CustomAuthError classes. AuthApiError always has a code property for identifying the server error and a status property encoding the HTTP status code.
Dart AuthException class hierarchy
All errors originating from the supabase.auth namespace in Dart are wrapped by the AuthException class. AuthApiException is an exception that originates from the Supabase Auth API. Errors classed as AuthApiException always have a code property for identifying the server error and a statusCode property encoding the HTTP status code.
Swift AuthError enum for API errors
All errors originating from the supabase.auth namespace in Swift are cases of the AuthError enum. The api(message:errorCode:underlyingData:underlyingResponse:) case represents errors from the Supabase Auth API and always has an errorCode property to identify the server error.
Python AuthError class hierarchy
All errors originating from the supabase.auth namespace in Python are wrapped by the AuthError class. AuthApiError is an error that originates from the Supabase Auth API. Errors classed as AuthApiError always have a code property for identifying the server error and a status property encoding the HTTP status code.
Kotlin auth exception hierarchy
All exceptions originating from the supabase.auth namespace in Kotlin are subclasses of RestException. Exception classes include AuthRestException (from Supabase Auth API with errorCode property), AuthWeakPasswordException (indicates password is too weak), and AuthSessionMissingException (indicates session is missing, user was logged out or deleted). All instances of AuthRestException and subclasses have an errorCode property.
C# GotrueException error properties
All exceptions originating from the supabase.Auth namespace in C# are wrapped by the GotrueException class. GotrueException exposes StatusCode (the HTTP status code from Supabase Auth API) and Reason (a FailureHint.Reason value that categorizes the error for branching without message parsing).
HTTP 403 Forbidden in Supabase Auth
HTTP 403 Forbidden is sent in rare situations where a certain Auth feature is not available for the user, and the developer is not checking a precondition whether that API is available for the user.
HTTP 422 Unprocessable Entity in Supabase Auth
HTTP 422 Unprocessable Entity is sent when the API request is accepted but cannot be processed because the user or Auth server is in a state where it cannot satisfy the request.
HTTP 500 Internal Server Error in Supabase Auth
HTTP 500 Internal Server Error indicates that the Auth server's service is degraded. It most often points to issues in database setup such as a misbehaving trigger on a schema, function, view or other database object.
HTTP 501 Not Implemented in Supabase Auth
HTTP 501 Not Implemented is sent when a feature is not enabled on the Auth server and the user is trying to use an API which requires it.
Best practice: error identification method
Always use error.code and error.name to identify errors, not string matching on error messages. Avoid relying solely on HTTP status codes, as they may change unexpectedly.
Supabase Auth error types categorization
Supabase Auth errors are generally categorized into two main types: API Errors which originate from the Supabase Auth API, and Client Errors which originate from the client library's state.
Related auth configuration sections
Supabase Auth has additional configuration sections available: Policies (for Row Level Security), Sign In / Providers (for authentication providers and login methods), Third Party Auth (for JWT-based TPA systems), Sessions (for session and refresh token settings), Rate limits (for traffic protection), Email Templates (for user emails), Custom SMTP (for email sending), Multi-Factor (for additional verification factors), URL Configuration (for site and redirect URLs), Attack Protection (for security settings), Auth Hooks (for Postgres functions or HTTP endpoints to customize auth behavior), Audit Logs (for tracking auth events), and Performance (for authentication server settings).
Identity types in Supabase Auth
Supabase Auth supports four types of identity: Email, Phone, OAuth, and SAML. A user can have more than one identity. Anonymous users have no identity until they link an identity to their user.
User identity object attributes
The user identity object contains the following attributes: | Attribute | Type | Description | |-----------|------|-------------| | provider_id | string | The provider id returned by the provider. If the provider is an OAuth provider, the id refers to the user's account with the OAuth provider. If the provider is email or phone, the id is the user's id from the auth.users table. | | user_id | string | The user's id that the identity is linked to. | | identity_data | object | The identity metadata. For OAuth and SAML identities, this contains information about the user from the provider. | | id | string | The unique id of the identity. | | provider | string | The provider name. | | email | string | A generated column that references the optional email property in the identity_data. | | created_at | string | The timestamp that the identity was created. | | last_sign_in_at | string | The timestamp that the identity was last used to sign in. | | updated_at | string | The timestamp that the identity was last updated. |
Supported OAuth and OIDC standards
Supabase OAuth 2.1 Server supports: OAuth 2.1 (latest specification with mandatory PKCE), OpenID Connect (ID tokens with openid scope, UserInfo endpoint, and OIDC discovery), standard scopes (openid, email, profile, and phone for controlling data access), dynamic client registration (automatic registration for MCP-compatible clients), and JWKS endpoint (public keys for third parties to validate tokens).
Supabase as OAuth 2.1 and OIDC identity provider
Supabase Auth can act as an OAuth 2.1 and OpenID Connect identity provider, allowing other applications and services to use your Supabase project as their authentication provider, similar to 'Sign in with Google' or 'Sign in with GitHub'.
OAuth 2.1 Server use cases
OAuth 2.1 Server enables: developer platforms and marketplaces allowing third-party developers to build integrations with 'Sign in with [Your App]' experiences controlled by Row Level Security; AI agents and automation to authenticate LLM tools and MCP servers accessing user data; mobile and desktop apps to issue OAuth tokens to first-party clients respecting Row Level Security; enterprise SSO providing standards-compliant identity federation.
OAuth 2.1 Server integration with existing Supabase Auth
OAuth 2.1 Server works with existing Supabase Auth configuration: users can authenticate using any enabled method (password, magic link, social providers, MFA, phone); Custom Access Token Hooks apply to OAuth tokens allowing customization of claims like audience or client-specific permissions; Row Level Security policies control data access using the client_id claim; all standard Supabase features (email templates, hooks, rate limiting) continue to work.
SAML terminology: Certificate
A Certificate is used to verify SAML assertions. Supabase Auth (the Service Provider) trusts assertions from an Identity Provider based on the signature attached to the assertion. The signature is verified according to the certificate present in the Metadata.
SAML terminology: Assertion Consumer Service (ACS) URL
The Assertion Consumer Service (ACS) URL is one of the most important SAML URLs. It is the URL where Supabase Auth accepts assertions from an identity provider. Once the identity provider verifies the user's identity, it redirects to this URL and the redirect request contains the assertion.
SAML terminology: Binding
Binding describes the way an identity provider communicates with Supabase Auth. Redirect binding uses HTTP 301 redirects. POST binding uses POST requests sent with form elements on a page. Artifact binding uses a more secure exchange over Redirect or POST.
SAML terminology: RelayState
RelayState is state used by Supabase Auth to hold information about a request to verify the identity of a user.
SAML terminology: Identity Provider (IdP)
An Identity Provider (IdP) is a service that manages user accounts at a company or organization. It verifies user identity and exchanges that information with Supabase Auth and other applications. It acts as a single source of truth for user identities and access rights. Commonly used identity providers include Microsoft Active Directory (Azure AD, Microsoft Entra), Okta, Google Workspaces (G Suite), PingIdentity, OneLogin, and many others. There are also self-hosted and on-prem versions sometimes accessible only via company VPN or specific locations.
SAML terminology: Service Provider (SP)
A Service Provider (SP) is the software asking for user information from an identity provider. In Supabase, the Service Provider is your project's Auth server.
SAML terminology: Assertion
An assertion is a statement issued by an identity provider that contains information about a user.