JavaScript Client Library

Create a new client for use in the browser.

You can initialize a new Supabase client using the createClient() method.

The Supabase client is your entrypoint to the rest of the Supabase functionality and is the easiest way to interact with everything we offer within the Supabase ecosystem.

Perform a SELECT query on the table or view.

• By default, Supabase projects return a maximum of 1,000 rows. This setting can be changed in your project's API settings. It's recommended that you keep it low to limit the payload size of accidental or malicious requests. You can use range() queries to paginate through your data.
• select() can be combined with Filters
• select() can be combined with Modifiers
• apikey is a reserved keyword if you're using the Supabase Platform and should be avoided as a column name.

Perform an INSERT into the table or view.

Perform an UPDATE on the table or view.

• update() should always be combined with Filters to target the item(s) you wish to update.

Perform an UPSERT on the table or view. Depending on the column(s) passed to onConflict, .upsert() allows you to perform the equivalent of .insert() if a row with the corresponding onConflict columns doesn't exist, or if it does exist, perform an alternative action depending on ignoreDuplicates.

• Primary keys must be included in values to use upsert.

Perform a DELETE on the table or view.

• delete() should always be combined with filters to target the item(s) you wish to delete.
• If you use delete() with filters and you have RLS enabled, only rows visible through SELECT policies are deleted. Note that by default no rows are visible, so you need at least one SELECT/ALL policy that makes the rows visible.
• When using delete().in(), specify an array of values to target multiple rows with a single query. This is particularly useful for batch deleting entries that share common criteria, such as deleting users by their IDs. Ensure that the array you provide accurately represents all records you intend to delete to avoid unintended data removal.

Perform a function call.

You can call Postgres functions as Remote Procedure Calls, logic in your database that you can execute from anywhere. Functions are useful when the logic rarely changes—like for password resets and updates.

To call Postgres functions on Read Replicas, use the get: true option.

Filters allow you to only return rows that match certain conditions.

Filters can be used on select(), update(), upsert(), and delete() queries.

If a Postgres function returns a table response, you can also apply filters.

Match only rows where column is equal to value.

Match only rows where column is not equal to value.

Match only rows where column is greater than value.

Match only rows where column is greater than or equal to value.

Match only rows where column is less than value.

Match only rows where column is less than or equal to value.

Match only rows where column matches pattern case-sensitively.

Match only rows where column matches pattern case-insensitively.

Match only rows where column IS value.

Match only rows where column is included in the values array.

Only relevant for jsonb, array, and range columns. Match only rows where column contains every element appearing in value.

Only relevant for jsonb, array, and range columns. Match only rows where every element appearing in column is contained by value.

Only relevant for range columns. Match only rows where every element in column is greater than any element in range.

Only relevant for range columns. Match only rows where every element in column is either contained in range or greater than any element in range.

Only relevant for range columns. Match only rows where every element in column is less than any element in range.

Only relevant for range columns. Match only rows where every element in column is either contained in range or less than any element in range.

Only relevant for range columns. Match only rows where column is mutually exclusive to range and there can be no element between the two ranges.

Only relevant for array and range columns. Match only rows where column and value have an element in common.

Only relevant for text and tsvector columns. Match only rows where column matches the query string in query.

• For more information, see Postgres full text search.

Match only rows where each column in query keys is equal to its associated value. Shorthand for multiple .eq()s.

Match only rows which doesn't satisfy the filter.

not() expects you to use the raw PostgREST syntax for the filter values.

Match only rows which satisfy at least one of the filters.

or() expects you to use the raw PostgREST syntax for the filter names and values.

Match only rows which satisfy the filter. This is an escape hatch - you should use the specific filter methods wherever possible.

filter() expects you to use the raw PostgREST syntax for the filter values.

Filters work on the row level—they allow you to return rows that only match certain conditions without changing the shape of the rows. Modifiers are everything that don't fit that definition—allowing you to change the format of the response (e.g., returning a CSV string).

Modifiers must be specified after filters. Some modifiers only apply for queries that return rows (e.g., select() or rpc() on a function that returns a table response).

Perform a SELECT on the query result.

Order the query result by column.

Limit the query result by count.

Limit the query result by starting at an offset (from) and ending at the offset (from + to). Only records within this range are returned. This respects the query order and if there is no order clause the range could behave unexpectedly. The from and to values are 0-based and inclusive: range(1, 3) will include the second, third and fourth rows of the query.

Set the AbortSignal for the fetch request.

You can use this to set a timeout for the request.

Return data as a single object instead of an array of objects.

Return data as a single object instead of an array of objects.

Return data as a string in CSV format.

Override the type of the returned data.

Return data as the EXPLAIN plan for the query.

For debugging slow queries, you can get the Postgres EXPLAIN execution plan of a query using the explain() method. This works on any query, even for rpc() or writes.

Explain is not enabled by default as it can reveal sensitive information about your database. It's best to only enable this for testing environments but if you wish to enable it for production you can provide additional protection by using a pre-request function.

Follow the Performance Debugging Guide to enable the functionality on your project.

• The auth methods can be accessed via the supabase.auth namespace.

• By default, the supabase client sets persistSession to true and attempts to store the session in local storage. When using the supabase client in an environment that doesn't support local storage, you might notice the following warning message being logged:

  No storage option exists to persist the session, which may result in unexpected behavior when using auth. If you want to set persistSession to true, please provide a storage option or you may set persistSession to false to disable this warning.

  This warning message can be safely ignored if you're not using auth on the server-side. If you are using auth and you want to set persistSession to true, you will need to provide a custom storage implementation that follows this interface.

• Any email links and one-time passwords (OTPs) sent have a default expiry of 24 hours. We have the following rate limits in place to guard against brute force attacks.

• The expiry of an access token can be set in the "JWT expiry limit" field in your project's auth settings. A refresh token never expires and can only be used once.

Creates a new user.

• 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:
  • When both Confirm email and Confirm phone (even when phone provider is disabled) are enabled in your project, an obfuscated/fake user object is returned.
  • When either Confirm email or Confirm phone (even when phone provider is disabled) is disabled, the error message, User already registered is returned.
• To fetch the currently logged-in user, refer to getUser().

Receive a notification every time an auth event happens.

• Subscribes to important events occurring on the user's session.
• Use on the frontend/client. It is less useful on the server.
• Events are emitted across tabs to keep your application's UI up-to-date. Some events can fire very frequently, based on the number of tabs open. Use a quick and efficient callback function, and defer or debounce as many operations as you can to be performed outside of the callback.
• Important: A callback can be an async function and it runs synchronously during the processing of the changes causing the event. You can easily create a dead-lock by using await on a call to another method of the Supabase library.
  • Avoid using async functions as callbacks.
  • Limit the number of await calls in async callbacks.
  • Do not use other Supabase functions in the callback function. If you must, dispatch the functions once the callback has finished executing. Use this as a quick way to achieve this:
    
    

    _10

    supabase.auth.onAuthStateChange((event, session) => {

    _10

    setTimeout(async () => {

    _10

    // await on other Supabase function here

    _10

    // this runs right after the callback has finished

    _10

    }, 0)

    _10

    })

    
    
• Emitted events:
  • INITIAL_SESSION
    • Emitted right after the Supabase client is constructed and the initial session from storage is loaded.
  • SIGNED_IN
    • Emitted each time a user session is confirmed or re-established, including on user sign in and when refocusing a tab.
    • Avoid making assumptions as to when this event is fired, this may occur even when the user is already signed in. Instead, check the user object attached to the event to see if a new user has signed in and update your application's UI.
    • This event can fire very frequently depending on the number of tabs open in your application.
  • SIGNED_OUT
    • Emitted when the user signs out. This can be after:
      • A call to supabase.auth.signOut().
      • After the user's session has expired for any reason:
        • User has signed out on another device.
        • The session has reached its timebox limit or inactivity timeout.
        • User has signed in on another device with single session per user enabled.
        • Check the User Sessions docs for more information.
    • Use this to clean up any local storage your application has associated with the user.
  • TOKEN_REFRESHED
    • Emitted each time a new access and refresh token are fetched for the signed in user.
    • It's best practice and highly recommended to extract the access token (JWT) and store it in memory for further use in your application.
      • Avoid frequent calls to supabase.auth.getSession() for the same purpose.
    • There is a background process that keeps track of when the session should be refreshed so you will always receive valid tokens by listening to this event.
    • The frequency of this event is related to the JWT expiry limit configured on your project.
  • USER_UPDATED
    • Emitted each time the supabase.auth.updateUser() method finishes successfully. Listen to it to update your application's UI based on new profile information.
  • PASSWORD_RECOVERY
    • Emitted instead of the SIGNED_IN event when the user lands on a page that includes a password recovery link in the URL.
    • Use it to show a UI to the user where they can reset their password.

Creates a new anonymous user.

• Returns an anonymous user
• It is recommended to set up captcha for anonymous sign-ins to prevent abuse. You can pass in the captcha token in the options param.

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

• Requires either an email and password or a phone number and password.

Allows signing in with an OIDC ID token. The authentication provider used should be enabled and configured.

Log in a user using magiclink or a one-time password (OTP).

• Requires either an email or phone number.
• This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
• If the user doesn't exist, signInWithOtp() will signup the user instead. To restrict this behavior, you can set shouldCreateUser in SignInWithPasswordlessCredentials.options to false.
• If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP.
• If you're using phone, you can configure whether you want the user to receive a OTP.
• The magic link's destination URL is determined by the SITE_URL.
• See redirect URLs and wildcards to add additional redirect URLs to your project.
• Magic links and OTPs share the same implementation. To send users a one-time code instead of a magic link, modify the magic link email template to include {{ .Token }} instead of {{ .ConfirmationURL }}.
• See our Twilio Phone Auth Guide for details about configuring WhatsApp sign in.

Log in an existing user via a third-party provider. This method supports the PKCE flow.

• This method is used for signing in using a third-party provider.
• Supabase supports many different third-party providers.

Attempts a single-sign on using an enterprise Identity Provider. A successful SSO attempt will redirect the current page to the identity provider authorization page. The redirect URL is implementation and SSO protocol specific.

• Before you can call this method you need to establish a connection to an identity provider. Use the CLI commands to do this.
• If you've associated an email domain to the identity provider, you can use the domain property to start a sign-in flow.
• In case you need to use a different way to start the authentication flow with an identity provider, you can use the providerId property. For example:
  • Mapping specific user email addresses with an identity provider.
  • Using different hints to identity the identity provider to be used by the user, like a company-specific page, IP address or other tracking information.

Inside a browser context, signOut() will remove the logged in user from the browser session and log them out - removing all items from localstorage and then trigger a "SIGNED_OUT" event.

• In order to use the signOut() method, the user needs to be signed in first.
• By default, signOut() uses the global scope, which signs out all other sessions that the user is logged into as well.
• Since Supabase Auth uses JWTs for authentication, the access token JWT will be valid until it's expired. When the user signs out, Supabase revokes the refresh token and deletes the JWT from the client-side. This does not revoke the JWT and it will still be valid until it expires.

Sends a password reset request to an email address. This method supports the PKCE flow.

• The password reset flow consist of 2 broad steps: (i) Allow the user to login via the password reset link; (ii) Update the user's password.
• The resetPasswordForEmail() only sends a password reset link to the user's email. To update the user's password, see updateUser().
• A SIGNED_IN and PASSWORD_RECOVERY event will be emitted when the password recovery link is clicked. You can use onAuthStateChange() to listen and invoke a callback function on these events.
• When the user clicks the reset link in the email they are redirected back to your application. You can configure the URL that the user is redirected to with the redirectTo parameter. See redirect URLs and wildcards to add additional redirect URLs to your project.
• After the user has been redirected successfully, prompt them for a new password and call updateUser():

Log in a user given a User supplied OTP or TokenHash received through mobile or email.

• The verifyOtp method takes in different verification types. If a phone number is used, the type can either be sms or phone_change. If an email address is used, the type can be one of the following: email, recovery, invite or email_change (signup and magiclink types are deprecated).
• The verification type used should be determined based on the corresponding auth method called before verifyOtp to sign up / sign-in a user.
• The TokenHash is contained in the email templates and can be used to sign in. You may wish to use the hash with Magic Links for the PKCE flow for Server Side Auth. See this guide for more details.

Returns the session, refreshing it if necessary.

• This method retrieves the current local session (i.e local storage).
• The session contains a signed JWT and unencoded session data.
• Since the unencoded session data is retrieved from the local storage medium, do not rely on it as a source of trusted data on the server. It could be tampered with by the sender. If you need verified, trustworthy user data, call getUser instead.
• If the session has an expired access token, this method will use the refresh token to get a new session.

Returns a new session, regardless of expiry status. Takes in an optional current session. If not passed in, then refreshSession() will attempt to retrieve it from getSession(). If the current session's refresh token is invalid, an error will be thrown.

• This method will refresh and return a new session whether the current one is expired or not.

Gets the current user details if there is an existing session. This method performs a network request to the Supabase Auth server, so the returned value is authentic and can be used to base authorization rules on.

• This method fetches the user object from the database instead of local session.
• This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server.
• Should always be used when checking for user authorization on the server. On the client, you can instead use getSession().session.user for faster results. getSession is insecure on the server.

Updates user data for a logged in user.

• In order to use the updateUser() method, the user needs to be signed in first.
• By default, email updates sends a confirmation link to both the user's current and new email. To only send a confirmation link to the user's new email, disable Secure email change in your project's email auth provider settings.

Gets all the identities linked to a user.

• The user needs to be signed in to call getUserIdentities().

Links an oauth identity to an existing user. This method supports the PKCE flow.

• The Enable Manual Linking option must be enabled from your project's authentication settings.
• The user needs to be signed in to call linkIdentity().
• If the candidate identity is already linked to the existing user or another user, linkIdentity() will fail.
• If linkIdentity is run in the browser, the user is automatically redirected to the returned URL. On the server, you should handle the redirect.

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.

• The Enable Manual Linking option must be enabled from your project's authentication settings.
• The user needs to be signed in to call unlinkIdentity().
• The user must have at least 2 identities in order to unlink an identity.
• The identity to be unlinked must belong to the user.

Sends a reauthentication OTP to the user's email or phone number. Requires the user to be signed-in.

• This method is used together with updateUser() when a user's password needs to be updated.
• If you require your user to reauthenticate before updating their password, you need to enable the Secure password change option in your project's email provider settings.
• A user is only require to reauthenticate before updating their password if Secure password change is enabled and the user hasn't recently signed in. A user is deemed recently signed in if the session was created in the last 24 hours.
• This method will send a nonce to the user's email. If the user doesn't have a confirmed email address, the method will send the nonce to the user's confirmed phone number instead.

Resends an existing signup confirmation email, email change email, SMS OTP or phone change OTP.

• Resends a signup confirmation, email change or phone change email to the user.
• Passwordless sign-ins can be resent by calling the signInWithOtp() method again.
• Password recovery emails can be resent by calling the resetPasswordForEmail() method again.
• This method will only resend an email or phone OTP to the user if there was an initial signup, email change or phone change request being made.
• You can specify a redirect url when you resend an email link using the emailRedirectTo option.

Sets the session data from the current session. If the current session is expired, setSession will take care of refreshing it to obtain a new session. If the refresh token or access token in the current session is invalid, an error will be thrown.

• This method sets the session using an access_token and refresh_token.
• If successful, a SIGNED_IN event is emitted.

Log in an existing user by exchanging an Auth Code issued during the PKCE flow.

• Used when flowType is set to pkce in client options.

Starts an auto-refresh process in the background. The session is checked every few seconds. Close to the time of expiration a process is started to refresh the session. If refreshing fails it will be retried for as long as necessary.

• Only useful in non-browser environments such as React Native or Electron.
• The Supabase Auth library automatically starts and stops proactively refreshing the session when a tab is focused or not.
• On non-browser platforms, such as mobile or desktop apps built with web technologies, the library is not able to effectively determine whether the application is focused or not.
• To give this hint to the application, you should be calling this method when the app is in focus and calling supabase.auth.stopAutoRefresh() when it's out of focus.

Stops an active auto refresh process running in the background (if any).

• Only useful in non-browser environments such as React Native or Electron.
• The Supabase Auth library automatically starts and stops proactively refreshing the session when a tab is focused or not.
• On non-browser platforms, such as mobile or desktop apps built with web technologies, the library is not able to effectively determine whether the application is focused or not.
• When your application goes in the background or out of focus, call this method to stop the proactive refreshing of the session.

This section contains methods commonly used for Multi-Factor Authentication (MFA) and are invoked behind the supabase.auth.mfa namespace.

Currently, there is support for time-based one-time password (TOTP) and phone verification code as the 2nd factor. Recovery codes are not supported but users can enroll multiple factors, with an upper limit of 10.

Having a 2nd factor for recovery frees the user of the burden of having to store their recovery codes somewhere. It also reduces the attack surface since multiple recovery codes are usually generated compared to just having 1 backup factor.

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.

• Use totp or phone as the factorType and use the returned id to create a challenge.
• To create a challenge, see mfa.challenge().
• To verify a challenge, see mfa.verify().
• To create and verify a TOTP challenge in a single step, see mfa.challengeAndVerify().
• To generate a QR code for the totp secret in Next.js, you can do the following:

• The challenge and verify steps are separated when using Phone factors as the user will need time to receive and input the code obtained from the SMS in challenge.

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

• An enrolled factor is required before creating a challenge.
• To verify a challenge, see mfa.verify().
• A phone factor sends a code to the user upon challenge. The channel defaults to sms unless otherwise specified.

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

• To verify a challenge, please create a challenge first.

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.

• Intended for use with only TOTP factors.
• An enrolled factor is required before invoking challengeAndVerify().
• Executes mfa.challenge() and mfa.verify() in a single step.

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

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

• Authenticator Assurance Level (AAL) is the measure of the strength of an authentication mechanism.
• In Supabase, having an AAL of aal1 refers to having the 1st factor of authentication such as an email and password or OAuth sign-in while aal2 refers to the 2nd factor of authentication such as a time-based, one-time-password (TOTP) or Phone factor.
• If the user has a verified factor, the nextLevel field will return aal2, else, it will return aal1.

• Any method under the supabase.auth.admin namespace requires a service_role key.
• These methods are considered admin methods and should be called on a trusted server. Never expose your service_role key in the browser.

Get user by id.

• Fetches the user object from the database based on the user's id.
• The getUserById() method requires the user's id which maps to the auth.users.id column.

Get a list of users.

• Defaults to return 50 users per page.

Creates a new user. This function should only be called on a server. Never expose your service_role key in the browser.

• To confirm the user's email address or phone number, set email_confirm or phone_confirm to true. Both arguments default to false.
• createUser() will not send a confirmation email to the user. You can use inviteUserByEmail() if you want to send them an email invite instead.
• If you are sure that the created user's email or phone number is legitimate and verified, you can set the email_confirm or phone_confirm param to true.

Delete a user. Requires a service_role key.

• The deleteUser() method requires the user's ID, which maps to the auth.users.id column.

Sends an invite link to an email address.

• Sends an invite link to the user's email address.
• The inviteUserByEmail() method is typically used by administrators to invite users to join the application.
• Note that PKCE is not supported when using inviteUserByEmail. This is because the browser initiating the invite is often different from the browser accepting the invite which makes it difficult to provide the security guarantees required of the PKCE flow.

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

• The following types can be passed into generateLink(): signup, magiclink, invite, recovery, email_change_current, email_change_new, phone_change.
• generateLink() only generates the email link for email_change_email if the Secure email change is enabled in your project's email auth provider settings.
• generateLink() handles the creation of the user for signup, invite and magiclink.

Updates the user data.

Deletes a factor on a user. This will log the user out of all active sessions if the deleted factor was verified.

Invokes a function

Invoke a Supabase Edge Function.

• Requires an Authorization header.
• Invoke params generally match the Fetch API spec.
• When you pass in a body to your function, we automatically attach the Content-Type header for Blob, ArrayBuffer, File, FormData and String. If it doesn't match any of these types we assume the payload is json, serialize it and attach the Content-Type header as application/json. You can override this behavior by passing in a Content-Type header of your own.
• Responses are automatically parsed as json, blob and form-data depending on the Content-Type header sent by your function. Responses are parsed as text by default.

Creates an event handler that listens to changes.

• By default, Broadcast and Presence are enabled for all projects.
• By default, listening to database changes is disabled for new projects due to database performance and security concerns. You can turn it on by managing Realtime's replication.
• You can receive the "previous" data for updates and deletes by setting the table's REPLICA IDENTITY to FULL (e.g., ALTER TABLE your_table REPLICA IDENTITY FULL;).
• Row level security is not applied to delete statements. When RLS is enabled and replica identity is set to full, only the primary key is sent to clients.

Unsubscribes and removes Realtime channel from Realtime client.

• Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.

Unsubscribes and removes all Realtime channels from Realtime client.

• Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.

Returns all Realtime channels.

Sends a message into the channel.

Broadcast a message to all connected clients to a channel.

• When using REST you don't need to subscribe to the channel
• REST calls are only available from 2.37.0 onwards

Creates a new Storage bucket

• RLS policy permissions required:
  • buckets table permissions: insert
  • objects table permissions: none
• Refer to the Storage guide on how access control works

Retrieves the details of an existing Storage bucket.

• RLS policy permissions required:
  • buckets table permissions: select
  • objects table permissions: none
• Refer to the Storage guide on how access control works

Retrieves the details of all Storage buckets within an existing project.

• RLS policy permissions required:
  • buckets table permissions: select
  • objects table permissions: none
• Refer to the Storage guide on how access control works

Updates a Storage bucket

• RLS policy permissions required:
  • buckets table permissions: select and update
  • objects table permissions: none
• Refer to the Storage guide on how access control works

Deletes an existing bucket. A bucket can't be deleted with existing objects inside it. You must first empty() the bucket.

• RLS policy permissions required:
  • buckets table permissions: select and delete
  • objects table permissions: none
• Refer to the Storage guide on how access control works

Removes all objects inside a single bucket.

• RLS policy permissions required:
  • buckets table permissions: select
  • objects table permissions: select and delete
• Refer to the Storage guide on how access control works

Uploads a file to an existing bucket.

• RLS policy permissions required:
  • buckets table permissions: none
  • objects table permissions: only insert when you are uploading new files and select, insert and update when you are upserting files
• Refer to the Storage guide on how access control works
• For React Native, using either Blob, File or FormData does not work as intended. Upload file using ArrayBuffer from base64 file data instead, see example below.

Downloads a file from a private bucket. For public buckets, make a request to the URL returned from getPublicUrl instead.

• RLS policy permissions required:
  • buckets table permissions: none
  • objects table permissions: select
• Refer to the Storage guide on how access control works

Lists all the files within a bucket.

• RLS policy permissions required:
  • buckets table permissions: none
  • objects table permissions: select
• Refer to the Storage guide on how access control works