Table of Contents

Interface IGotrueClient<TUser, TSession>

Namespace
Supabase.Gotrue.Interfaces
Assembly
Supabase.Gotrue.dll

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.

public interface IGotrueClient<TUser, TSession> : IGettableHeaders where TUser : User where TSession : Session

Type Parameters

TUser
TSession
Inherited Members
IGettableHeaders.GetHeaders

Examples

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

Properties

CurrentSession

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.

TSession? CurrentSession { get; }

Property Value

TSession

CurrentUser

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. Update(UserAttributes)>

TUser? CurrentUser { get; }

Property Value

TUser

Online

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.

bool Online { get; set; }

Property Value

bool

Options

Returns the client options.

ClientOptions Options { get; }

Property Value

ClientOptions

Methods

AddDebugListener(Action<string, Exception?>)

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.

void AddDebugListener(Action<string, Exception?> listener)

Parameters

listener Action<string, Exception>

Callback method for debug messages

AddStateChangedListener(AuthEventHandler)

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

Constants.AuthState

void AddStateChangedListener(IGotrueClient<TUser, TSession>.AuthEventHandler authEventHandler)

Parameters

authEventHandler IGotrueClient<TUser, TSession>.AuthEventHandler

Challenge(MfaChallengeParams)

Prepares a challenge used to verify that a user has access to a MFA factor.

Task<MfaChallengeResponse?> Challenge(MfaChallengeParams mfaChallengeParams)

Parameters

mfaChallengeParams MfaChallengeParams

Returns

Task<MfaChallengeResponse>

ChallengeAndVerify(MfaChallengeAndVerifyParams)

Helper method which creates a challenge and immediately uses the given code to verify against it thereafter. The verification code is provided by the user by entering a code seen in their authenticator app.

Task<Session?> ChallengeAndVerify(MfaChallengeAndVerifyParams mfaChallengeAndVerifyParams)

Parameters

mfaChallengeAndVerifyParams MfaChallengeAndVerifyParams

Returns

Task<Session>

ClearStateChangedListeners()

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.

void ClearStateChangedListeners()

Debug(string, Exception?)

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

void Debug(string message, Exception? e = null)

Parameters

message string
e Exception

Enroll(MfaEnrollParams)

Starts the enrollment process for a new Multi-Factor Authentication (MFA) factor. This method creates a new unverified factor. To verify a factor, present the QR code or secret to the user and ask them to add it to their authenticator app. The user has to enter the code from their authenticator app to verify it.

Upon verifying a factor, all other sessions are logged out and the current session's authenticator level is promoted to aal2.

Task<MfaEnrollResponse?> Enroll(MfaEnrollParams mfaEnrollParams)

Parameters

mfaEnrollParams MfaEnrollParams

Returns

Task<MfaEnrollResponse>

ExchangeCodeForSession(string, string)

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

Task<TSession?> ExchangeCodeForSession(string codeVerifier, string authCode)

Parameters

codeVerifier string
authCode string

Returns

Task<TSession>

GetAuthenticatorAssuranceLevel()

Returns the Authenticator Assurance Level (AAL) for the active session.

  • aal1 (or null) means that the user's identity has been verified only with a conventional login (email+password, OTP, magic link, social login, etc.).
  • aal2 means that the user's identity has been verified both with a conventional login and at least one MFA factor.

Although this method returns a promise, it's fairly quick (microseconds) and rarely uses the network. You can use this to check whether the current user needs to be shown a screen to verify their MFA factors.

Task<MfaGetAuthenticatorAssuranceLevelResponse?> GetAuthenticatorAssuranceLevel()

Returns

Task<MfaGetAuthenticatorAssuranceLevelResponse>

GetSessionFromUrl(Uri, bool)

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

Task<TSession?> GetSessionFromUrl(Uri uri, bool storeSession = true)

Parameters

uri Uri
storeSession bool

Returns

Task<TSession>

GetUser(string)

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

Task<TUser?> GetUser(string jwt)

Parameters

jwt string

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

Returns

Task<TUser>

LinkIdentity(Provider, SignInOptions)

Links an oauth identity to an existing user.

This method requires the PKCE flow.

Task<ProviderAuthState> LinkIdentity(Constants.Provider provider, SignInOptions options)

Parameters

provider Constants.Provider

Provider to Link

options SignInOptions

Returns

Task<ProviderAuthState>

ListFactors()

Returns the list of MFA factors enabled for this user

Task<MfaListFactorsResponse?> ListFactors()

Returns

Task<MfaListFactorsResponse>

LoadSession()

Loads the session from the persistence layer.

void LoadSession()

NotifyAuthStateChange(AuthState)

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.

void NotifyAuthStateChange(Constants.AuthState stateChanged)

Parameters

stateChanged Constants.AuthState

Reauthenticate()

Used for re-authenticating a user in password changes.

See: https://github.com/supabase/gotrue#get-reauthenticate

Task<bool> Reauthenticate()

Returns

Task<bool>

Exceptions

GotrueException

RefreshSession()

Refreshes the currently logged in User's Session.

Task<TSession?> RefreshSession()

Returns

Task<TSession>

RefreshToken()

Refreshes a Token using the current session.

Task RefreshToken()

Returns

Task

RemoveStateChangedListener(AuthEventHandler)

Removes a specified listener from event state changes.

void RemoveStateChangedListener(IGotrueClient<TUser, TSession>.AuthEventHandler authEventHandler)

Parameters

authEventHandler IGotrueClient<TUser, TSession>.AuthEventHandler

ResetPasswordForEmail(ResetPasswordForEmailOptions)

Sends a password reset request to an email address.

Supports the PKCE Flow (the verifier from ResetPasswordForEmailState will be combined with ExchangeCodeForSession(string, string) in response)

Task<ResetPasswordForEmailState> ResetPasswordForEmail(ResetPasswordForEmailOptions options)

Parameters

options ResetPasswordForEmailOptions

Returns

Task<ResetPasswordForEmailState>

ResetPasswordForEmail(string)

Sends a reset request to an email address.

Task<bool> ResetPasswordForEmail(string email)

Parameters

email string

Returns

Task<bool>

RetrieveSessionAsync()

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.

Task<TSession?> RetrieveSessionAsync()

Returns

Task<TSession>

SendMagicLink(string, SignInOptions?)

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.

Task<bool> SendMagicLink(string email, SignInOptions? options = null)

Parameters

email string
options SignInOptions

Returns

Task<bool>

SetPersistence(IGotrueSessionPersistence<TSession>)

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

void SetPersistence(IGotrueSessionPersistence<TSession> persistence)

Parameters

persistence IGotrueSessionPersistence<TSession>

SetSession(string, string, bool)

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 SignedOut event.
  3. Decode token 3a. If expired (or bool forceAccessTokenRefresh set), force an access token refresh. 3b. If not expired, set the CurrentSession and retrieve CurrentUser from the server using the accessToken.
  4. Raise a `SignedIn event if successful.
Task<TSession> SetSession(string accessToken, string refreshToken, bool forceAccessTokenRefresh = false)

Parameters

accessToken string
refreshToken string
forceAccessTokenRefresh bool

Returns

Task<TSession>

Exceptions

GotrueException

Raised when token combination is invalid.

Settings()

Retrieves the settings from the server

Task<Settings?> Settings()

Returns

Task<Settings>

Shutdown()

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.

void Shutdown()

SignIn(Provider, SignInOptions?)

Retrieves a ProviderAuthState to redirect to for signing in with a Constants.Provider.

This will likely be paired with a PKCE flow (set in SignInOptions) - after redirecting the user to the flow, you should pair with ExchangeCodeForSession(string, string)

Task<ProviderAuthState> SignIn(Constants.Provider provider, SignInOptions? options = null)

Parameters

provider Constants.Provider
options SignInOptions

Returns

Task<ProviderAuthState>

SignIn(SignInType, string, string?, string?)

Log in an existing user, or login via a third-party provider.

Task<TSession?> SignIn(Constants.SignInType type, string identifierOrToken, string? password = null, string? scopes = null)

Parameters

type Constants.SignInType

Type of Credentials being passed

identifierOrToken string

An email, phone, or RefreshToken

password string

Password to account (optional if RefreshToken)

scopes string

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

Returns

Task<TSession>

SignIn(string, SignInOptions?)

Sends a magic link login email to the specified email.

Task<bool> SignIn(string email, SignInOptions? options = null)

Parameters

email string
options SignInOptions

Returns

Task<bool>

SignIn(string, string)

Signs in a User.

Task<TSession?> SignIn(string email, string password)

Parameters

email string
password string

Returns

Task<TSession>

SignInAnonymously(SignInAnonymouslyOptions?)

Creates a new anonymous user.

Task<TSession?> SignInAnonymously(SignInAnonymouslyOptions? options = null)

Parameters

options SignInAnonymouslyOptions

Returns

Task<TSession>

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

SignInWithIdToken(Provider, string, string?, string?, string?)

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].

Task<TSession?> SignInWithIdToken(Constants.Provider provider, string idToken, string? accessToken = null, string? nonce = null, string? captchaToken = null)

Parameters

provider Constants.Provider

Provider name or OIDC iss value identifying which provider should be used to verify the provided token. Supported names: google, apple, azure, facebook

idToken string

OIDC ID token issued by the specified provider. The iss claim in the ID token must match the supplied provider. Some ID tokens contain an at_hash which require that you provide an access_token value to be accepted properly. If the token contains a nonce claim you must supply the nonce used to obtain the ID token.

accessToken string

If the ID token contains an at_hash claim, then the hash of this value is compared to the value in the ID token.

nonce string

If the ID token contains a nonce claim, then the hash of this value is compared to the value in the ID token.

captchaToken string

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

Returns

Task<TSession>

Remarks

Calling this method will eliminate the current session (if any).

SignInWithOtp(SignInWithPasswordlessEmailOptions)

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.

Task<PasswordlessSignInState> SignInWithOtp(SignInWithPasswordlessEmailOptions options)

Parameters

options SignInWithPasswordlessEmailOptions

Returns

Task<PasswordlessSignInState>

Remarks

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

SignInWithOtp(SignInWithPasswordlessPhoneOptions)

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.

Task<PasswordlessSignInState> SignInWithOtp(SignInWithPasswordlessPhoneOptions options)

Parameters

options SignInWithPasswordlessPhoneOptions

Returns

Task<PasswordlessSignInState>

Remarks

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

SignInWithPassword(string, string)

Log in an existing user with an email and password or phone and password.

Task<TSession?> SignInWithPassword(string email, string password)

Parameters

email string
password string

Returns

Task<TSession>

SignInWithSSO(Guid, SignInWithSSOOptions?)

Sign in using single sign on (SSO) as supported by supabase To use SSO you need to first set up the providers using the supabase CLI please follow the guide found here: https://supabase.com/docs/guides/auth/enterprise-sso/auth-sso-saml

Task<SSOResponse?> SignInWithSSO(Guid providerId, SignInWithSSOOptions? options = null)

Parameters

providerId Guid

The guid of the provider you wish to use, obtained from running supabase sso list from the CLI

options SignInWithSSOOptions

The redirect uri and captcha token, if any

Returns

Task<SSOResponse>

The Uri returned from supabase auth that a user can use to sign in to their given SSO provider (okta, microsoft entra, gsuite ect...)

SignInWithSSO(string, SignInWithSSOOptions?)

Sign in using single sign on (SSO) as supported by supabase To use SSO you need to first set up the providers using the supabase CLI please follow the guide found here: https://supabase.com/docs/guides/auth/enterprise-sso/auth-sso-saml

Task<SSOResponse?> SignInWithSSO(string domain, SignInWithSSOOptions? options = null)

Parameters

domain string

Your organizations email domain to use for sign in, this domain needs to already be registered with supabase by running the CLI commands Example: google.com

options SignInWithSSOOptions

The redirect uri and captcha token, if any

Returns

Task<SSOResponse>

The Uri returned from supabase auth that a user can use to sign in to their given SSO provider (okta, microsoft entra, gsuite ect...)

SignOut(SignOutScope)

Signs out and invalidates all sessions for a user.

Task SignOut(Constants.SignOutScope scope = SignOutScope.Global)

Parameters

scope Constants.SignOutScope

Determines which sessions should be invalidated. By default, it will invalidate all session for a user

Returns

Task

SignUp(SignUpType, string, string, SignUpOptions?)

Signs up a user

Task<TSession?> SignUp(Constants.SignUpType type, string identifier, string password, SignUpOptions? options = null)

Parameters

type Constants.SignUpType
identifier string
password string
options SignUpOptions

Object containing redirectTo and optional user metadata (data)

Returns

Task<TSession>

Remarks

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 User.

SignUp(string, string, SignUpOptions?)

Signs up a user by email address.

Task<TSession?> SignUp(string email, string password, SignUpOptions? options = null)

Parameters

email string
password string
options SignUpOptions

Object containing redirectTo and optional user metadata (data)

Returns

Task<TSession>

Remarks

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.

Unenroll(MfaUnenrollParams)

Unenroll removes a MFA factor. A user has to have an aal2 authenticator level in order to unenroll a verified factor.

Task<MfaUnenrollResponse?> Unenroll(MfaUnenrollParams mfaUnenrollParams)

Parameters

mfaUnenrollParams MfaUnenrollParams

Returns

Task<MfaUnenrollResponse>

UnlinkIdentity(UserIdentity)

Unlinks an identity from a user by deleting it. The user will no longer be able to sign in with that identity once it's unlinked.

Task<bool> UnlinkIdentity(UserIdentity userIdentity)

Parameters

userIdentity UserIdentity

Identity to be unlinked

Returns

Task<bool>

Update(UserAttributes)

Updates a User.

Task<TUser?> Update(UserAttributes attributes)

Parameters

attributes UserAttributes

Returns

Task<TUser>

Verify(MfaVerifyParams)

Verifies a code against a challenge. The verification code is provided by the user by entering a code seen in their authenticator app.

Task<Session?> Verify(MfaVerifyParams mfaVerifyParams)

Parameters

mfaVerifyParams MfaVerifyParams

Returns

Task<Session>

VerifyOTP(string, string, EmailOtpType)

Log in a user give a user supplied OTP received via email.

Task<TSession?> VerifyOTP(string email, string token, Constants.EmailOtpType type = EmailOtpType.MagicLink)

Parameters

email string
token string
type Constants.EmailOtpType

Defaults to MagicLink

Returns

Task<TSession>

VerifyOTP(string, string, MobileOtpType)

Log in a user given a User supplied OTP received via mobile.

Task<TSession?> VerifyOTP(string phone, string token, Constants.MobileOtpType type = MobileOtpType.SMS)

Parameters

phone string

The user's phone number.

token string

Token sent to the user's phone.

type Constants.MobileOtpType

SMS or phone change

Returns

Task<TSession>

VerifyTokenHash(string, EmailOtpType)

Log in a user given the token hash used in an email confirmation link.

Task<TSession?> VerifyTokenHash(string tokenHash, Constants.EmailOtpType type = EmailOtpType.Email)

Parameters

tokenHash string
type Constants.EmailOtpType

Returns

Task<TSession>
Edit this page