Supabase.Gotrue

Admin client for interacting with the Gotrue API. Intended for use on servers or other secure environments. This client does NOT manage user sessions or track any other state.

The initialized client options.

Initialize the client with a service key.

A valid JWT. Must be a full-access API key (e.g. 'service_role' or 'supabase_admin').

Headers sent to the API on every request.

The underlying API requests object that sends the requests

The service key used to authenticate with the API.

The REST calls to the Gotrue API.

Function that can be set to return dynamic headers. Headers specified in the constructor will ALWAYS take precedence over headers returned by this function.

Headers to be sent with every request. These will be merged with any headers returned by GetHeaders.

Creates a new API client

Signs a user up using an email address and password.

Optional Signup data.

Logs in an existing user using their email address.

Log in a user using magiclink or a one-time password (OTP). If the `{{ .ConfirmationURL }}` variable is specified in the email template, a magiclink will be sent. If the `{{ .Token }}` variable is specified in the email template, an OTP will be sent. If you're using phone sign-ins, only an OTP will be sent. You won't be able to send a magiclink for phone sign-ins. Be aware that you may get back an error message that will not distinguish between the cases where the account does not exist or, that the account can only be accessed via social login. Do note that you will need to configure a Whatsapp sender on Twilio if you are using phone sign in with the 'whatsapp' channel. The whatsapp channel is not supported on other providers at this time.

Creates a new anonymous user.

A session where the is_anonymous claim in the access token JWT set to true

Allows signing in with an ID token issued by certain supported providers. The [idToken] is verified for validity and a new session is established. This method of signing in only supports [Provider.Google] or [Provider.Apple].

A supported provider (Google, Apple) InvalidProviderException

Sends a magic login link to an email address.

Sends an invite link to an email address.

this token needs role 'supabase_admin' or 'service_role'

Signs up a new user using their phone number and a password.The phone number of the user.

The phone number of the user. The password of the user. Optional Signup data.

Logs in an existing user using their phone number and password.

The phone number of the user. The password of the user.

Sends a mobile OTP via SMS. Will register the account if it doesn't already exist

phone The user's phone number WITH international prefix

Send User supplied Mobile OTP to be verified

The user's phone number WITH international prefix token that user was sent to their mobile phone e.g. SMS or phone change

Send User supplied Email OTP to be verified

The user's email address token that user was sent to their mobile phone Type of verification, e.g. invite, recovery, etc.

Sends a reset request to an email address.

Sends a password reset request to an email address. This Method supports the PKCE Flow

Create a temporary object with all configured headers and adds the Authorization token to be used on request methods

JWT

Generates the relevant login URI for a third-party provider.

Generated verifier (probably from GetUrlForProvider) The received Auth Code Callback

Removes a logged-in session.

Gets User Details

Get User details by Id

A valid JWT. Must be a full-access API key (e.g. service_role key). userID

Updates the User data

Lists users

A valid JWT. Must be a full-access API key (e.g. service_role key). A string for example part of the email Snake case string of the given key, currently only created_at is supported asc or desc, if null desc is used page to show for pagination items per page for pagination

Create a user

A valid JWT. Must be a full-access API key (e.g. service_role key). Additional administrative details

Update user by Id

A valid JWT. Must be a full-access API key (e.g. service_role key). userID User attributes e.g. email, password, etc.

Sends a re-authentication request, used for password changes. See: https://github.com/supabase/gotrue#get-reauthenticate

The user's auth token.

Delete a user

The user uid you want to remove. A valid JWT. Must be a full-access API key (e.g. service_role key).

Calls the GoTrue server to get the settings (for example, if email auto confirmation is turned on)

mpose up -d

Generates email links and OTPs to be sent via a custom email provider.

Generates a new Session given a user's access token and refresh token.

The underlying API requests object that sends the requests

Handlers for notifications of state changes.

Gets notifications if there is a failure not visible by exceptions (e.g. background thread refresh failure)

Object called to persist the session (e.g. filesystem or cookie)

Get the TokenRefresh object, if it exists

Initializes the GoTrue stateful client. You will likely want to at least specify a ClientOptions.Url Sessions are not automatically retrieved when this object is created. If you want to load the session from your persistence store, GotrueSessionPersistence . If you want to load/refresh the session, RetrieveSessionAsync . For a typical client application, you'll want to load the session from persistence and then refresh it. If your application is listening for session changes, you'll get two SignIn notifications if the persisted session is valid - one for the session loaded from disk, and a second on a successful session refresh. var client = new Supabase.Gotrue.Client(options); client.LoadSession(); await client.RetrieveSessionAsync();

Parses a out of a 's Query parameters.

Headers sent to the API on every request.

Saves the session

Clears the session

Class representation options available to the .

Gotrue Endpoint

Headers to be sent with subsequent requests.

Should the Client automatically handle refreshing the User's Token?

Ask the TokenRefresh system to log extra debug info

By default, the Client will attempt to refresh the token when roughly 1/5 of the time is left before expiration (assuming AutoRefreshToken is true). The default expiration time for GoTrue servers is 3600 (1 hour), with a maximum of 604,800 seconds (one week). If you set the expiration to one week, you may want to refresh the token a bit more frequently. This setting allows you to set a custom threshold for when the client should AutoRefreshToken. The default value is 14400 seconds (4 hours). In this scenario, if you set the server expiration to one week and leave this value set to the default, as long as the user logs in at least once a week they should stay logged in indefinitely.

Very unlikely this flag needs to be changed except in very specific contexts. Enables tests to be E2E tests to be run without requiring users to have confirmed emails - mirrors the Gotrue server's configuration.

Constants used throughout the Gotrue Client

URL for the Gotrue server. Defaults to localhost:9999.

Providers available to Supabase Ref: https://supabase.github.io/gotrue-js/modules.html#Provider

States that the Auth Client will raise events for.

Specifies the functionality expected from the `SignIn` method

Represents an OAuth Flow type

Specifies the functionality expected from the `SignUp` method

Manages the debug listeners for the Gotrue Client. You'll want to install a debug listener to get debug information back - especially for errors from the background RefreshToken thread.

Add a debug listener to the Gotrue Client. This will be called with debug information

Send a debug message to all debug listeners

Maps Supabase server errors to hints based on the status code and the contents of the error message.

Best effort guess at why the exception was thrown.

The reason for the error could not be determined.

The client is set to run offline or the network is unavailable.

The user's email address has not been confirmed.

The user's email address and password are invalid.

The user's password is invalid.

The user's login is invalid.

The user's email address is invalid.

The user's phone number is invalid.

The user's information is incomplete.

The user is already registered.

Server rejected due to number of requests

The refresh token is invalid.

The refresh token expired.

This operation requires a bearer/service key (do not include this key in a client app)

No/invalid session found

Something wrong with the URL to session transformation

Detects the reason for the error based on the status code and the contents of the error message.

Errors from the GoTrue server are wrapped by this exception

Something with wrong with Gotrue / Auth

Short description of the error source

Something with wrong with Gotrue / Auth

Short description of the error source The underlying exception

Something with wrong with Gotrue / Auth

Short description of the error source Best effort attempt to detect the reason for the failure

Something with wrong with Gotrue / Auth

Short description of the error source Assigned reason

The HTTP response from the server

The content of the HTTP response from the server

The HTTP status code from the server

Adds the best-effort reason for the failure

Best guess at what caused the error from the server, see

Options for Generating an Email Link

Mapping of link types that can be generated.

Generate a signup link.

Generate an invite link.

Generate a magic link.

Generate a recovery link.

Generate an email change link to be sent to the current email address.

Generate an email change link to be sent to the new email address.

The type of link being generated

The User's Email

Only required if generating a signup link.

The user's new email. Only required if type is 'email_change_current' or 'email_change_new'.

A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column. The `data` should be a JSON encodable object that includes user-specific info, such as their first and last name.

The URL which will be appended to the email link generated.

Constructs options, additional properties may need to be assigned depending on - is required for and - is required for - is optional for

Shortcut options for

Constructs options for

is optional

Shortcut options for

Constructs options for

Shortcut options for

Constructs options for

Utility methods to assist with flow. Includes nonce generation and verification.

Generates a nonce (code verifier) Used with PKCE flow and Apple/Google Sign in. Paired with Sourced from: https://stackoverflow.com/a/65220376/3629438

Generates a PKCE SHA256 code challenge given a nonce (code verifier) Paired with Sourced from: https://stackoverflow.com/a/65220376/3629438

Generates a SHA256 nonce given a rawNonce, used Apple/Google Sign in.

Adds query params to a given Url

Helper to make a request using the defined parameters to an API Endpoint and coerce into a model.

Helper to make a request using the defined parameters to an API Endpoint.

Interface for the Gotrue Admin Client (auth).

Creates a user using the admin key (not the anonymous key). Used in trusted server environments, not client apps.

Gets a user from a user's JWT. This is using the GoTrue server to validate a user's JWT.

Gets a user by ID from the server using the admin key (not the anonymous key).

Sends an email to the user.

Lists users

A string for example part of the email Snake case string of the given key, currently only created_at is supported asc or desc, if null desc is used page to show for pagination items per page for pagination

Updates a User using the service key

Update user by Id

Generates email links and OTPs to be sent via a custom email provider.

Options for this call. `Password` is required for , `Data` is an optional parameter for .

GoTrue stateful Client. This class is best used as a long-lived singleton object in your application. You can attach listeners to be notified of changes to the user log in state, a persistence system for sessions across application launches, and more. It includes a (optional, on by default) background thread that runs to refresh the user's session token. Check out the test suite for examples of use.

var client = new Supabase.Gotrue.Client(options); var user = await client.SignIn("user@email.com", "fancyPassword");

Indicates if the client should be considered online or offline. In a server environment, this client would likely always be online. On a mobile client, you will want to pair this with a network implementation to turn this on and off as the device goes online and offline.

The current Session as managed by this client. Does not refresh tokens or have any other side effects. You probably don't want to directly make changes to this object - you'll want to use other methods on this class to make changes.

The currently logged in User. This is a local cache of the current session User. To persist modifications to the User you'll want to use other methods. >

The method that is called when there is a user state change.

Sets the persistence implementation for the client (e.g. file system, local storage, etc).

Adds a listener to be notified when the user state changes (e.g. the user logs in, logs out, the token is refreshed, etc).

Removes a specified listener from event state changes.

Clears all of the listeners from receiving event state changes. WARNING: The persistence handler and refresh token thread are installed as state change listeners. Clearing the listeners will also delete these handlers.

Notifies all listeners that the current user auth state has changed. This is mainly used internally to fire notifications - most client applications won't need this.

Converts a URL to a session. For client apps, this probably requires setting up URL handlers.

Refreshes the currently logged in User's Session.

Sends a reset request to an email address.

Sends a password reset request to an email address. Supports the PKCE Flow (the `verifier` from will be combined with in response)

Typically called as part of the startup process for the client. This will take the currently loaded session (e.g. from a persistence implementation) and if possible attempt to refresh it. If the loaded session is expired or invalid, it will log the user out.

Sends a Magic email login link to the specified email. Most of the interesting configuration for this flow is done in the Supabase/GoTrue admin panel.

Sets a new session given a user's access token and their refresh token. 1. Will destroy the current session (if existing) 2. Raise a event. 3. Decode token 3a. If expired (or bool set), force an access token refresh. 3b. If not expired, set the and retrieve from the server using the . 4. Raise a ` event if successful.

Raised when token combination is invalid.

Type of Credentials being passed An email, phone, or RefreshToken Password to account (optional if `RefreshToken`) A space-separated list of scopes granted to the OAuth application.

Sends a magic link login email to the specified email.

Signs in a User.

Calling this method will wipe out the current session (if any)

Retrieves a to redirect to for signing in with a . This will likely be paired with a PKCE flow (set in SignInOptions) - after redirecting the user to the flow, you should pair with

A supported provider (Google, Apple) Provided from External Library Provided from External Library Provided from External Library Calling this method will eliminate the current session (if any). InvalidProviderException

Creates a new anonymous user.

A session where the is_anonymous claim in the access token JWT set to true

Logs in an existing user via a third-party provider.

Signs up a user

Calling this method will log out the current user session (if any). By default, the user needs to verify their email address before logging in. To turn this off, disable confirm email in your project. Confirm email determines if users need to confirm their email address after signing up. - If Confirm email is enabled, a user is returned but session is null. - If Confirm email is disabled, both a user and a session are returned. When the user confirms their email address, they are redirected to the SITE_URL by default. You can modify your SITE_URL or add additional redirect URLs in your project. If signUp() is called for an existing confirmed user: - If Confirm email is enabled in your project, an obfuscated/fake user object is returned. - If Confirm email is disabled, the error message, User already registered is returned. To fetch the currently logged-in user, refer to . Object containing redirectTo and optional user metadata (data)

Signs up a user by email address.

By default, the user needs to verify their email address before logging in. To turn this off, disable Confirm email in your project. Confirm email determines if users need to confirm their email address after signing up. - If Confirm email is enabled, a user is returned but session is null. - If Confirm email is disabled, both a user and a session are returned. When the user confirms their email address, they are redirected to the SITE_URL by default. You can modify your SITE_URL or add additional redirect URLs in your project. If signUp() is called for an existing confirmed user: - If Confirm email is enabled in your project, an obfuscated/fake user object is returned. - If Confirm email is disabled, the error message, User already registered is returned. To fetch the currently logged-in user, refer to User . Object containing redirectTo and optional user metadata (data)

Used for re-authenticating a user in password changes. See: https://github.com/supabase/gotrue#get-reauthenticate

Signs out a user and invalidates the current token.

Updates a User.

The user's phone number. Token sent to the user's phone. SMS or phone change

Defaults to MagicLink

Add a listener to get errors that occur outside of a typical Exception flow. In particular, this is used to get errors and messages from the background thread that automatically manages refreshing the user's token.

Callback method for debug messages

Loads the session from the persistence layer.

Retrieves the settings from the server

Returns the client options.

Get User details by JWT. Can be used to validate a JWT.

A valid JWT. Must be a JWT that originates from a user.

Posts messages and exceptions to the debug listener. This is particularly useful for sorting out issues with the refresh token background thread.

Let all of the listeners know that the stateless client is being shutdown. In particular, the background thread that is used to refresh the token is stopped.

Refreshes a Token using the current session.

Interface for a session persistence auth state handler.

The persistence implementation for the client (e.g. file system, local storage, etc).

Routes auth state changes to the persistence implementation.

Interface for session persistence. As a reminder, make sure you handle exceptions and other error conditions in your implementation.

Saves the session to the persistence implementation.

Destroys the session in the persistence implementation. Usually this means deleting the session file or clearing local storage.

Loads the session from the persistence implementation. Returns null if there is no session.

A Stateless Gotrue Client

var options = new StatelessClientOptions { Url = "https://mygotrueurl.com" }; var user = await client.SignIn("user@email.com", "fancyPassword", options);

Create a user

A valid JWT. Must be a full-access API key (e.g. service_role key).

Create a user

A valid JWT. Must be a full-access API key (e.g. service_role key).

Deletes a User.

this token needs role 'supabase_admin' or 'service_role'

Initialize/retrieve the underlying API for this client

Parses a out of a 's Query parameters.

Get User details by JWT. Can be used to validate a JWT.

A valid JWT. Must be a JWT that originates from a user.

Get User details by Id

A valid JWT. Must be a full-access API key (e.g. service_role key).

Sends an invite email link to the specified email.

this token needs role 'supabase_admin' or 'service_role'

Lists users

Refreshes a Token

Sends a reset request to an email address.

Sends a Magic email login link to the specified email.

Retrieves a Url to redirect to for signing in with a . This method will need to be combined with when the Application receives the Oauth Callback.

var client = Supabase.Gotrue.Client.Initialize(options); var url = client.SignIn(Provider.Github); // Do Redirect User // Example code Application.HasReceivedOauth += async (uri) => { var session = await client.GetSessionFromUri(uri, true); }

Type of Credentials being passed An email, phone, or RefreshToken Password to account (optional if `RefreshToken`)

Sends a Magic email login link to the specified email.

Signs in a User with an email address and password.

Logout a User This will revoke all refresh tokens for the user. JWT tokens will still be valid for stateless auth until they expire.

Signs up a user

Type of signup Phone or Email Object containing redirectTo and optional user metadata (data)

Signs up a user by email address

Object containing redirectTo and optional user metadata (data)

Updates a User's attributes

Update user by Id

A valid JWT. Must be a full-access API key (e.g. service_role key).

The user's phone number. Token sent to the user's phone.

Retrieve the current settings for the Gotrue instance.

A utility class that represents options for sending a User an Invitation

The URL which will be appended to the email link sent to the user's email address. Once clicked the user will end up on this URL.

A custom data object to store additional metadata about the user. This maps to the `auth.users.user_metadata` column.

A Network status system to pair with the Client. https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/network-info

True if the network has been checked.

A delegate for listening to network changes.

Adds a listener to the network status system.

Removes a listener from the network status system.

The that this network status system is attached to.

Pings the URL in the to check if the network is online. https://PROJECTID.supabase.co/auth/v1/settings

Starts the network status system. This will listen to the OS for network changes, and also does a ping check to confirm the current network status.

Removes the network status system checker from the OS.

A utility class that represents a successful response from a request to send a user Passwordless Sign In.

PKCE Verifier generated if using the PKCE flow type.

Manages the persistence of the Gotrue Session. You'll want to install a persistence listener to persist user sessions between app restarts.

Create a new persistence listener

If you install a persistence listener, it will be called when the user signs in and signs out.

Represents an OAuth Provider's URI and Parameters. For use with Provider Auth, PKCE Auth, and ID Token auth.

The Generated Provider's URI

The PKCE Verifier nonce, only set during a PKCE auth flow.

Constructor

A utility class that represents a successful response from a request to send a user's password reset using the PKCE flow.

The Email representing the user's account whose password is being reset.

The OAuth Flow Type.

The URL to send the user to after they click the password reset link.

Verification token received when the user completes the captcha on the site.

PKCE Verifier generated if using the PKCE flow type.

Initializes a new instance of the class with the provided email.

The email of the user account for which the password is being reset.

A utility class that represents a successful response from a request to send a user's password reset using the PKCE flow.

PKCE Verifier generated if using the PKCE flow type.

A wrapper class from which all Responses derive.

The HTTP response message.

The HTTP response content as a string.

An extended user response returned when generating a link.

The email link to send to the user. The action_link follows the following format: auth/v1/verify?type={verification_type}&token={hashed_token}&redirect_to={redirect_to}

The raw email OTP. You should send this in the email if you want your users to verify using an OTP instead of the action link.

The hashed token appended to the action link.

The URL appended to the action link.

The verification type that the email link is associated to.

Represents a Gotrue Session

The expiration date of this session, in UTC time.

Returns true if the session has expired

Settings data retrieved from the GoTrue server.

A custom data object to store the user's metadata. This maps to the `auth.users.raw_user_meta_data` column. The `data` should be a JSON serializable object that includes user-specific info, such as their first and last name.

Verification token received when the user completes the captcha on the site.

Options used for signing in a user.

A URL or mobile address to send the user to after they are confirmed.

A space-separated list of scopes granted to the OAuth application.

An object of key-value pairs containing query parameters granted to the OAuth application.

Represents an OAuth Flow type, defaults to `Implicit` PKCE is recommended for mobile and server-side applications.

Options used for signing in a user with passwordless Options

A custom data object to store the user's metadata. This maps to the `auth.users.user_metadata` column. The `data` should be a JSON serializable object that includes user-specific info, such as their first and last name.

Verification token received when the user completes the captcha on the site.

If set to false, this method will not create a new user. Defaults to true.

The user's email address.

The redirect url embedded in the email link.

Represents an OAuth Flow type, defaults to `Implicit` PKCE is recommended for mobile and server-side applications.

The user's email address.

Represents a messaging channel to use for sending the OTP.

SMS

The user's phone number

Messaging channel to use (e.g. whatsapp or sms), Defaults to SMS.

The user's phone number

Options used for signing up a user.

Optional user metadata.

Class representation options available to the .

Gotrue Endpoint

Headers to be sent with subsequent requests.

Manages the auto-refresh of the Gotrue Session.

Internal timer reference for token refresh AutoRefreshToken

Turn on debug logging for the TokenRefresh

Sets up the TokenRefresh class, bound to a specific client

Turns the auto-refresh timer on or off based on the current auth state

The Client and Session data

Sets up the auto-refresh timer

The timer calls this method at the configured interval to refresh the token. If the user is offline, it won't try to refresh the token.

Create a new refresh timer. We pass to ensure the handler only runs once. We create a new timer after each refresh so that each refresh runs in a new thread. This keeps the refresh going if a thread crashes. Creating a thread each refresh is not so expensive when the refresh interval is an hour or longer.

Interval should be t - (1/5(n)) (i.e. if session time (t) 3600s, attempt refresh at 2880s or 720s (1/5) seconds before expiration)

Represents a Gotrue User Ref: https://supabase.github.io/gotrue-js/interfaces/User.html

Ref: https://supabase.github.io/gotrue-js/interfaces/AdminUserAttributes.html

A custom data object for app_metadata that. Can be any JSON serializable data. Only a service role can modify Note: GoTrue does not yest support creating a user with app metadata (see: https://github.com/supabase/gotrue-js/blob/d7b334a4283027c65814aa81715ffead262f0bfa/test/GoTrueApi.test.ts#L45)

A custom data object for user_metadata. Can be any JSON serializable data. Only a service role can modify.

Sets if a user has confirmed their email address. Only a service role can modify

Sets if a user has confirmed their phone number. Only a service role can modify

Ref: https://supabase.github.io/gotrue-js/interfaces/UserAttributes.html

A custom data object for user_metadata that a user can modify.Can be any JSON.

Ref: https://supabase.github.io/gotrue-js/interfaces/VerifyEmailOTPParams.html

Ref: https://supabase.github.io/gotrue-js/interfaces/UserIdentity.html