Javascript Reference v2.0

Initializing

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.

Parameters
    supabaseUrl
    REQUIRED
    string

    The unique Supabase URL which is supplied when you create a new project in your project dashboard.

    supabaseKey
    REQUIRED
    string

    The unique Supabase Key which is supplied when you create a new project in your project dashboard.

    options
    Optional
    SupabaseClientOptions

import { createClient } from '@supabase/supabase-js'

// Create a single supabase client for interacting with your database
const supabase = createClient('https://xyzcompany.supabase.co', 'public-anon-key')

Fetch data

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.
Parameters
    columns
    Optional
    Query

    The columns to retrieve, separated by commas. Columns can be renamed when returned with customName:columnName

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .select()

Insert data

Perform an INSERT into the table or view.

Parameters
    values
    REQUIRED
    object[]

    The values to insert. Pass an object to insert a single row or an array to insert multiple rows.

    options
    Optional
    object

    Named parameters


const { error } = await supabase
  .from('countries')
  .insert({ id: 1, name: 'Denmark' })

Update data

Perform an UPDATE on the table or view.

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

    The values to update with

    options
    Optional
    object

    Named parameters


const { error } = await supabase
  .from('countries')
  .update({ name: 'Australia' })
  .eq('id', 1)

Upsert data

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.
Parameters
    values
    REQUIRED
    object[]

    The values to upsert with. Pass an object to upsert a single row or an array to upsert multiple rows.

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .upsert({ id: 1, name: 'Albania' })
  .select()

Delete data

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.
Parameters
    options
    Optional
    object

    Named parameters


const { error } = await supabase
  .from('countries')
  .delete()
  .eq('id', 1)

Call a Postgres function

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.

create or replace function hello_world() returns text as $$
  select 'Hello world';
$$ language sql;
Parameters
    fn
    REQUIRED
    FunctionName

    The function name to call

    args
    Optional
    object

    The arguments to pass to the function call

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase.rpc('hello_world')

Using filters

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.


const { data, error } = await supabase
  .from('cities')
  .select('name, country_id')
  .eq('name', 'The Shire')    // Correct

const { data, error } = await supabase
  .from('cities')
  .eq('name', 'The Shire')    // Incorrect
  .select('name, country_id')

Column is equal to a value

Match only rows where column is equal to value.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    NonNullable

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .eq('name', 'Albania')

Column is not equal to a value

Match only rows where column is not equal to value.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    any

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .neq('name', 'Albania')

Column is greater than a value

Match only rows where column is greater than value.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    any

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .gt('id', 2)

Column is greater than or equal to a value

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

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    any

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .gte('id', 2)

Column is less than a value

Match only rows where column is less than value.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    any

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .lt('id', 2)

Column is less than or equal to a value

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

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    any

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .lte('id', 2)

Column matches a pattern

Match only rows where column matches pattern case-sensitively.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    pattern
    REQUIRED
    string

    The pattern to match with


const { data, error } = await supabase
  .from('countries')
  .select()
  .like('name', '%Alba%')

Column matches a case-insensitive pattern

Match only rows where column matches pattern case-insensitively.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    pattern
    REQUIRED
    string

    The pattern to match with


const { data, error } = await supabase
  .from('countries')
  .select()
  .ilike('name', '%alba%')

Column is a value

Match only rows where column IS value.

Parameters
    column
    REQUIRED
    string

    The column to filter on

    value
    REQUIRED
    null | boolean

    The value to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .is('name', null)

Column is in an array

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

Parameters
    column
    REQUIRED
    string

    The column to filter on

    values
    REQUIRED
    object

    The values array to filter with


const { data, error } = await supabase
  .from('countries')
  .select()
  .in('name', ['Albania', 'Algeria'])

Column contains every element in a value

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

Parameters
    column
    REQUIRED
    string

    The jsonb, array, or range column to filter on

    value
    REQUIRED
    object

    The jsonb, array, or range value to filter with


const { data, error } = await supabase
  .from('issues')
  .select()
  .contains('tags', ['is:open', 'priority:low'])

Contained by value

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

Parameters
    column
    REQUIRED
    string

    The jsonb, array, or range column to filter on

    value
    REQUIRED
    object

    The jsonb, array, or range value to filter with


const { data, error } = await supabase
  .from('classes')
  .select('name')
  .containedBy('days', ['monday', 'tuesday', 'wednesday', 'friday'])

Greater than a range

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

Parameters
    column
    REQUIRED
    string

    The range column to filter on

    range
    REQUIRED
    string

    The range to filter with


const { data, error } = await supabase
  .from('reservations')
  .select()
  .rangeGt('during', '[2000-01-02 08:00, 2000-01-02 09:00)')

Greater than or equal to a 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.

Parameters
    column
    REQUIRED
    string

    The range column to filter on

    range
    REQUIRED
    string

    The range to filter with


const { data, error } = await supabase
  .from('reservations')
  .select()
  .rangeGte('during', '[2000-01-02 08:30, 2000-01-02 09:30)')

Less than a range

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

Parameters
    column
    REQUIRED
    string

    The range column to filter on

    range
    REQUIRED
    string

    The range to filter with


const { data, error } = await supabase
  .from('reservations')
  .select()
  .rangeLt('during', '[2000-01-01 15:00, 2000-01-01 16:00)')

Less than or equal to a 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.

Parameters
    column
    REQUIRED
    string

    The range column to filter on

    range
    REQUIRED
    string

    The range to filter with


const { data, error } = await supabase
  .from('reservations')
  .select()
  .rangeLte('during', '[2000-01-01 14:00, 2000-01-01 16:00)')

Mutually exclusive to a 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.

Parameters
    column
    REQUIRED
    string

    The range column to filter on

    range
    REQUIRED
    string

    The range to filter with


const { data, error } = await supabase
  .from('reservations')
  .select()
  .rangeAdjacent('during', '[2000-01-01 12:00, 2000-01-01 13:00)')

With a common element

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

Parameters
    column
    REQUIRED
    string

    The array or range column to filter on

    value
    REQUIRED
    object

    The array or range value to filter with


const { data, error } = await supabase
  .from('issues')
  .select('title')
  .overlaps('tags', ['is:closed', 'severity:high'])

Match a string

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

Parameters
    column
    REQUIRED
    string

    The text or tsvector column to filter on

    query
    REQUIRED
    string

    The query text to match with

    options
    Optional
    object

    Named parameters

Match an associated value

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

Parameters
    query
    REQUIRED
    Record

    The object to filter with, with column names as keys mapped to their filter values


const { data, error } = await supabase
  .from('countries')
  .select('name')
  .match({ id: 2, name: 'Albania' })

Don't match the filter

Match only rows which doesn't satisfy the filter.

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

1.not('id', 'in', '(5,6,7)')  // Use `()` for `in` filter
2.not('arraycol', 'cs', '{"a","b"}')  // Use `cs` for `contains()`, `{}` for array values
Parameters
    column
    REQUIRED
    string

    The column to filter on

    operator
    REQUIRED
    string

    The operator to be negated to filter with, following PostgREST syntax

    value
    REQUIRED
    any

    The value to filter with, following PostgREST syntax


const { data, error } = await supabase
  .from('countries')
  .select()
  .not('name', 'is', null)

Match at least one filter

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.

1.or('id.in.(5,6,7), arraycol.cs.{"a","b"}')  // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
2.or('id.in.(5,6,7), arraycol.cd.{"a","b"}')  // Use `cd` for `containedBy()`
Parameters
    filters
    REQUIRED
    string

    The filters to use, following PostgREST syntax

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .select('name')
  .or('id.eq.2,name.eq.Algeria')

Match the filter

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.

1.filter('id', 'in', '(5,6,7)')  // Use `()` for `in` filter
2.filter('arraycol', 'cs', '{"a","b"}')  // Use `cs` for `contains()`, `{}` for array values
Parameters
    column
    REQUIRED
    string

    The column to filter on

    operator
    REQUIRED
    string

    The operator to filter with, following PostgREST syntax

    value
    REQUIRED
    any

    The value to filter with, following PostgREST syntax


const { data, error } = await supabase
  .from('countries')
  .select()
  .filter('name', 'in', '("Algeria","Japan")')

Using modifiers

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

Return data after inserting

Perform a SELECT on the query result.

Parameters
    columns
    Optional
    Query

    The columns to retrieve, separated by commas


const { data, error } = await supabase
  .from('countries')
  .upsert({ id: 1, name: 'Algeria' })
  .select()

Order the results

Order the query result by column.

Parameters
    column
    REQUIRED
    string

    The column to order by

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .select('id', 'name')
  .order('id', { ascending: false })

Limit the number of rows returned

Limit the query result by count.

Parameters
    count
    REQUIRED
    number

    The maximum number of rows to return

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .select('name')
  .limit(1)

Limit the query to a range

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.

Parameters
    from
    REQUIRED
    number

    The starting index from which to limit the result

    to
    REQUIRED
    number

    The last index to which to limit the result

    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .select('name')
  .range(0, 1)

Set an abort signal

Set the AbortSignal for the fetch request.

Parameters
    signal
    REQUIRED
    AbortSignal

    The AbortSignal to use for the fetch request


const ac = new AbortController()
ac.abort()
const { data, error } = await supabase
  .from('very_big_table')
  .select()
  .abortSignal(ac.signal)

Retrieve one row of data

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


const { data, error } = await supabase
  .from('countries')
  .select('name')
  .limit(1)
  .single()

Retrieve zero or one row of data

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


const { data, error } = await supabase
  .from('countries')
  .select()
  .eq('name', 'Singapore')
  .maybeSingle()

Retrieve as a CSV

Return data as a string in CSV format.


const { data, error } = await supabase
  .from('countries')
  .select()
  .csv()

Override type of successful response

Override the type of the returned data.


const { data } = await supabase
  .from('countries')
  .select()
  .returns<MyType>()

Using explain

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.

Parameters
    options
    Optional
    object

    Named parameters


const { data, error } = await supabase
  .from('countries')
  .select()
  .explain()

Overview

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


import { createClient } from '@supabase/supabase-js'

const supabase = createClient(supabase_url, anon_key)

Create a new user

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().
Parameters
    credentials
    REQUIRED
    SignUpWithPasswordCredentials

const { data, error } = await supabase.auth.signUp({
  email: '[email protected]',
  password: 'example-password',
})

Listen to auth events

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:
      1supabase.auth.onAuthStateChange((event, session) => {
      2  setTimeout(async () => {
      3    // await on other Supabase function here
      4    // this runs right after the callback has finished
      5  }, 0)
      6})
  • 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.
Parameters
    callback
    REQUIRED
    function

    A callback function to be invoked when an auth event happens.


const { data } = supabase.auth.onAuthStateChange((event, session) => {
  console.log(event, session)

  if (event === 'INITIAL_SESSION') {
    // handle initial session
  } else if (event === 'SIGNED_IN') {
    // handle sign in event
  } else if (event === 'SIGNED_OUT') {
    // handle sign out event
  } else if (event === 'PASSWORD_RECOVERY') {
    // handle password recovery event
  } else if (event === 'TOKEN_REFRESHED') {
    // handle token refreshed event
  } else if (event === 'USER_UPDATED') {
    // handle user updated event
  }
})

// call unsubscribe to remove the callback
data.subscription.unsubscribe()

Create an anonymous user

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.
Parameters
    credentials
    Optional
    SignInAnonymouslyCredentials

const { data, error } = await supabase.auth.signInAnonymously({
  options: {
    captchaToken
  }
});

Sign in a user

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.
Parameters
    credentials
    REQUIRED
    SignInWithPasswordCredentials

const { data, error } = await supabase.auth.signInWithPassword({
  email: '[email protected]',
  password: 'example-password',
})

Sign in with ID Token

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

Parameters
    credentials
    REQUIRED
    SignInWithIdTokenCredentials

const { data, error } = await supabase.auth.signInWithIdToken({
  provider: 'google',
  token: 'your-id-token'
})

Sign in a user through OTP

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 behaviour, 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.
Parameters
    credentials
    REQUIRED
    SignInWithPasswordlessCredentials

const { data, error } = await supabase.auth.signInWithOtp({
  email: '[email protected]',
  options: {
    emailRedirectTo: 'https://example.com/welcome'
  }
})

Sign in a user through OAuth

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.
Parameters
    credentials
    REQUIRED
    SignInWithOAuthCredentials

const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github'
})

Sign in a user through SSO

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.
Parameters
    params
    REQUIRED
    SignInWithSSO

  // You can extract the user's email domain and use it to trigger the
  // authentication flow with the correct identity provider.

  const { data, error } = await supabase.auth.signInWithSSO({
    domain: 'company.com'
  })

  if (data?.url) {
    // redirect the user to the identity provider's authentication flow
    window.location.href = data.url
  }

Sign out a user

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.
Parameters
    options
    Optional
    SignOut

const { error } = await supabase.auth.signOut()

Send a password reset request

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():
1const { data, error } = await supabase.auth.updateUser({
2  password: new_password
3})
Parameters
    email
    REQUIRED
    string

    The email address of the user.

    options
    Optional
    object

const { data, error } = await supabase.auth.resetPasswordForEmail(email, {
  redirectTo: 'https://example.com/update-password',
})

Verify and log in through OTP

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.
Parameters
    params
    REQUIRED
    VerifyOtpParams

const { data, error } = await supabase.auth.verifyOtp({ phone, token, type: 'sms'})

Retrieve a session

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.

const { data, error } = await supabase.auth.getSession()

Retrieve 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.
Parameters
    currentSession
    Optional
    object

    The current session. If passed in, it must contain a refresh token.


const { data, error } = await supabase.auth.refreshSession()
const { session, user } = data

Retrieve a user

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.
Parameters
    jwt
    Optional
    string

    Takes in an optional access token JWT. If no JWT is provided, the JWT from the current session is used.


const { data: { user } } = await supabase.auth.getUser()

Update a user

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.
Parameters
    attributes
    REQUIRED
    UserAttributes
    options
    Optional
    object

const { data, error } = await supabase.auth.updateUser({
  email: '[email protected]'
})

Retrieve identities linked to a user

Gets all the identities linked to a user.

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

const { data, error } = await supabase.auth.getUserIdentities()

Link an identity to a user

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.
Parameters
    credentials
    REQUIRED
    SignInWithOAuthCredentials

Unlink an identity from a user

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.
Parameters
    identity
    REQUIRED
    UserIdentity

Send a password reauthentication nonce

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.

const { data, error } = await supabase.auth.reauthenticate()

Resend an OTP

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.
Parameters
    credentials
    REQUIRED
    ResendParams

const { data, error } = await supabase.auth.resend({
  type: 'signup',
  email: '[email protected]',
  options: {
    emailRedirectTo: 'https://example.com/welcome'
  }
})

Set the session data

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.

  • setSession() takes in a refresh token and uses it to get a new session.
  • The refresh token can only be used once to obtain a new session.
  • Refresh token rotation is enabled by default on all projects to guard against replay attacks.
  • You can configure the REFRESH_TOKEN_REUSE_INTERVAL which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.
Parameters
    currentSession
    REQUIRED
    object

    The current session that minimally contains an access token and refresh token.


  const { data, error } = await supabase.auth.setSession({
    access_token,
    refresh_token
  })

Exchange an auth code for a session

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.
Parameters
    authCode
    REQUIRED
    string

supabase.auth.exchangeCodeForSession('34e770dd-9ff9-416c-87fa-43b31d7ef225')

Start auto-refresh session (non-browser)

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.

import { AppState } from 'react-native'

// make sure you register this only once!
AppState.addEventListener('change', (state) => {
  if (state === 'active') {
    supabase.auth.startAutoRefresh()
  } else {
    supabase.auth.stopAutoRefresh()
  }
})

Stop auto-refresh session (non-browser)

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.

import { AppState } from 'react-native'

// make sure you register this only once!
AppState.addEventListener('change', (state) => {
  if (state === 'active') {
    supabase.auth.startAutoRefresh()
  } else {
    supabase.auth.stopAutoRefresh()
  }
})

Auth MFA

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

Currently, we only support time-based one-time password (TOTP) as the 2nd factor. We don't support recovery codes but we allow users to enroll more than 1 TOTP factor, with an upper limit of 10.

Having a 2nd TOTP 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 TOTP factor.

Enroll a 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.

  • Currently, totp is the only supported factorType. The returned id should be used to create a challenge.
  • To create a challenge, see mfa.challenge().
  • To verify a challenge, see mfa.verify().
  • To create and verify a challenge in a single step, see mfa.challengeAndVerify().
  • To generate a QR code for the totp secret in nextjs, you can do the following:
1<Image src={data.totp.qr_code} alt={data.totp.uri} layout="fill"></Image>
Parameters
    params
    REQUIRED
    MFAEnrollParams

const { data, error } = await supabase.auth.mfa.enroll({
  factorType: 'totp',
  friendlyName: 'your_friendly_name'
})

// Use the id to create a challenge.
// The challenge can be verified by entering the code generated from the authenticator app.
// The code will be generated upon scanning the qr_code or entering the secret into the authenticator app.
const { id, type, totp: { qr_code, secret, uri }, friendly_name } = data

Create a challenge

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

Parameters
    params
    REQUIRED
    MFAChallengeParams

const { data, error } = await supabase.auth.mfa.challenge({
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225'
})

Verify a challenge

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

Parameters
    params
    REQUIRED
    MFAVerifyParams

const { data, error } = await supabase.auth.mfa.verify({
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
  challengeId: '4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15',
  code: '123456'
})

Create and verify a challenge

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.

Parameters
    params
    REQUIRED
    MFAChallengeAndVerifyParams

const { data, error } = await supabase.auth.mfa.challengeAndVerify({
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
  code: '123456'
})

Unenroll a factor

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

Parameters
    params
    REQUIRED
    MFAUnenrollParams

const { data, error } = await supabase.auth.mfa.unenroll({
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
})

Get Authenticator Assurance Level

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).
  • If the user has a verified factor, the nextLevel field will return aal2, else, it will return aal1.

const { data, error } = await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
const { currentLevel, nextLevel, currentAuthenticationMethods } = data

Auth Admin

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

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(supabase_url, service_role_key, {
  auth: {
    autoRefreshToken: false,
    persistSession: false
  }
})

// Access auth admin api
const adminAuthClient = supabase.auth.admin

Retrieve a user

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.
Parameters
    uid
    REQUIRED
    string

    The user's unique identifier

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


const { data, error } = await supabase.auth.admin.getUserById(1)

List all users

Get a list of users.

  • Defaults to return 50 users per page.
Parameters
    params
    Optional
    PageParams

    An object which supports page and perPage as numbers, to alter the paginated results.


const { data: { users }, error } = await supabase.auth.admin.listUsers()

Create a user

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.
Parameters
    attributes
    REQUIRED
    AdminUserAttributes

const { data, error } = await supabase.auth.admin.createUser({
  email: '[email protected]',
  password: 'password',
  user_metadata: { name: 'Yoda' }
})

Delete a user

Delete a user. Requires a service_role key.

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

    The user id you want to remove.

    shouldSoftDelete
    Optional
    boolean

    If true, then the user will be soft-deleted (setting deleted_at to the current timestamp and disabling their account while preserving their data) from the auth schema. Defaults to false for backward compatibility.

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


const { data, error } = await supabase.auth.admin.deleteUser(
  '715ed5db-f090-4b8c-a067-640ecee36aa0'
)

Send an email invite link

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 acecpting the invite which makes it difficult to provide the security guarantees required of the PKCE flow.
Parameters
    email
    REQUIRED
    string

    The email address of the user.

    options
    Optional
    object

    Additional options to be included when inviting.


const { data, error } = await supabase.auth.admin.inviteUserByEmail('[email protected]')

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.
Parameters
    params
    REQUIRED
    GenerateLinkParams

Update a user

Updates the user data.

Parameters
    uid
    REQUIRED
    string
    attributes
    REQUIRED
    AdminUserAttributes

    The data you want to update.

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


const { data: user, error } = await supabase.auth.admin.updateUserById(
  '6aa5d0d4-2a9f-4483-b6c8-0cf4c6c98ac4',
  { email: '[email protected]' }
)

List all factors for a user

Lists all factors associated to a user.

Parameters
    params
    REQUIRED
    AuthMFAAdminListFactorsParams

const { data, error } = await supabase.auth.admin.mfa.listFactors()

Delete a factor for a user

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

Parameters
    params
    REQUIRED
    AuthMFAAdminDeleteFactorParams

const { data, error } = await supabase.auth.admin.mfa.deleteFactor({
  id: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
  userId: 'a89baba7-b1b7-440f-b4bb-91026967f66b',
})

Invokes a Supabase Edge Function.

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, serialise it and attach the Content-Type header as application/json. You can override this behaviour 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.
Parameters
    functionName
    REQUIRED
    string

    The name of the Function to invoke.

    options
    Optional
    FunctionInvokeOptions

    Options for invoking the Function.


const { data, error } = await supabase.functions.invoke('hello', {
  body: { foo: 'bar' }
})

Subscribe to channel

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.
Parameters
    type
    REQUIRED
    "broadcast"
    filter
    REQUIRED
    object
    callback
    REQUIRED
    function

supabase
  .channel('room1')
  .on('broadcast', { event: 'cursor-pos' }, payload => {
    console.log('Cursor position received!', payload)
  })
  .subscribe((status) => {
    if (status === 'SUBSCRIBED') {
      channel.send({
        type: 'broadcast',
        event: 'cursor-pos',
        payload: { x: Math.random(), y: Math.random() },
      })
    }
  })

Unsubscribe from a channel

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.
Parameters
    channel
    REQUIRED
    default

    The name of the Realtime channel.


supabase.removeChannel(myChannel)

Unsubscribe from all channels

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.

supabase.removeAllChannels()

Retrieve all channels

Returns all Realtime channels.


const channels = supabase.getChannels()

Broadcast a message

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
Parameters
    args
    REQUIRED
    object

    Arguments to send to channel

    opts
    Optional
    object

    Options to be used during the send process


supabase
  .channel('room1')
  .subscribe((status) => {
    if (status === 'SUBSCRIBED') {
      channel.send({
        type: 'broadcast',
        event: 'cursor-pos',
        payload: { x: Math.random(), y: Math.random() },
      })
    }
  })

Create a bucket

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
Parameters
    id
    REQUIRED
    string

    A unique identifier for the bucket you are creating.

    options
    Optional
    object

const { data, error } = await supabase
  .storage
  .createBucket('avatars', {
    public: false,
    allowedMimeTypes: ['image/png'],
    fileSizeLimit: 1024
  })

Retrieve a bucket

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
Parameters
    id
    REQUIRED
    string

    The unique identifier of the bucket you would like to retrieve.


const { data, error } = await supabase
  .storage
  .getBucket('avatars')

List all buckets

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

const { data, error } = await supabase
  .storage
  .listBuckets()

Update a bucket

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
Parameters
    id
    REQUIRED
    string

    A unique identifier for the bucket you are updating.

    options
    REQUIRED
    object

const { data, error } = await supabase
  .storage
  .updateBucket('avatars', {
    public: false,
    allowedMimeTypes: ['image/png'],
    fileSizeLimit: 1024
  })

Delete a bucket

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
Parameters
    id
    REQUIRED
    string

    The unique identifier of the bucket you would like to delete.


const { data, error } = await supabase
  .storage
  .deleteBucket('avatars')

Empty a bucket

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
Parameters
    id
    REQUIRED
    string

    The unique identifier of the bucket you would like to empty.


const { data, error } = await supabase
  .storage
  .emptyBucket('avatars')

Upload a file

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.
Parameters
    path
    REQUIRED
    string

    The file path, including the file name. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to upload.

    fileBody
    REQUIRED
    FileBody

    The body of the file to be stored in the bucket.

    fileOptions
    Optional
    FileOptions

const avatarFile = event.target.files[0]
const { data, error } = await supabase
  .storage
  .from('avatars')
  .upload('public/avatar1.png', avatarFile, {
    cacheControl: '3600',
    upsert: false
  })

Download a file

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
Parameters
    path
    REQUIRED
    string

    The full path and file name of the file to be downloaded. For example folder/image.png.

    options
    Optional
    object

const { data, error } = await supabase
  .storage
  .from('avatars')
  .download('folder/avatar1.png')

List all files in a bucket

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
Parameters
    path
    Optional
    string

    The folder path.

    options
    Optional
    SearchOptions
    parameters
    Optional
    FetchParameters

const { data, error } = await supabase
  .storage
  .from('avatars')
  .list('folder', {
    limit: 100,
    offset: 0,
    sortBy: { column: 'name', order: 'asc' },
  })

Replace an existing file

Replaces an existing file at the specified path with a new one.

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: update and select
  • Refer to the Storage guide on how access control works
  • For React Native, using either Blob, File or FormData does not work as intended. Update file using ArrayBuffer from base64 file data instead, see example below.
Parameters
    path
    REQUIRED
    string

    The relative file path. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to update.

    fileBody
    REQUIRED
    object

    The body of the file to be stored in the bucket.

    fileOptions
    Optional
    FileOptions

const avatarFile = event.target.files[0]
const { data, error } = await supabase
  .storage
  .from('avatars')
  .update('public/avatar1.png', avatarFile, {
    cacheControl: '3600',
    upsert: true
  })

Move an existing file

Moves an existing file to a new path in the same bucket.

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

    The original file path, including the current file name. For example folder/image.png.

    toPath
    REQUIRED
    string

    The new file path, including the new file name. For example folder/image-new.png.


const { data, error } = await supabase
  .storage
  .from('avatars')
  .move('public/avatar1.png', 'private/avatar2.png')

Copy an existing file

Copies an existing file to a new path in the same bucket.

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: insert and select
  • Refer to the Storage guide on how access control works
Parameters
    fromPath
    REQUIRED
    string

    The original file path, including the current file name. For example folder/image.png.

    toPath
    REQUIRED
    string

    The new file path, including the new file name. For example folder/image-copy.png.


const { data, error } = await supabase
  .storage
  .from('avatars')
  .copy('public/avatar1.png', 'private/avatar2.png')

Delete files in a bucket

Deletes files within the same bucket

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: delete and select
  • Refer to the Storage guide on how access control works
Parameters
    paths
    REQUIRED
    string[]

    An array of files to delete, including the path and file name. For example ['folder/image.png'].


const { data, error } = await supabase
  .storage
  .from('avatars')
  .remove(['folder/avatar1.png'])

Create a signed URL

Creates a signed URL. Use a signed URL to share a file for a fixed amount of time.

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

    The file path, including the current file name. For example folder/image.png.

    expiresIn
    REQUIRED
    number

    The number of seconds until the signed URL expires. For example, 60 for a URL which is valid for one minute.

    options
    Optional
    object

const { data, error } = await supabase
  .storage
  .from('avatars')
  .createSignedUrl('folder/avatar1.png', 60)

Create signed URLs

Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time.

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: select
  • Refer to the Storage guide on how access control works
Parameters
    paths
    REQUIRED
    string[]

    The file paths to be downloaded, including the current file names. For example ['folder/image.png', 'folder2/image2.png'].

    expiresIn
    REQUIRED
    number

    The number of seconds until the signed URLs expire. For example, 60 for URLs which are valid for one minute.

    options
    Optional
    object

const { data, error } = await supabase
  .storage
  .from('avatars')
  .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60)

Create signed upload URL

Creates a signed upload URL. Signed upload URLs can be used to upload files to the bucket without further authentication. They are valid for 2 hours.

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

    The file path, including the current file name. For example folder/image.png.


const { data, error } = await supabase
  .storage
  .from('avatars')
  .createSignedUploadUrl('folder/cat.jpg')

Upload to a signed URL

Upload a file with a token generated from createSignedUploadUrl.

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

    The file path, including the file name. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to upload.

    token
    REQUIRED
    string

    The token generated from createSignedUploadUrl

    fileBody
    REQUIRED
    FileBody

    The body of the file to be stored in the bucket.

    fileOptions
    Optional
    FileOptions

const { data, error } = await supabase
  .storage
  .from('avatars')
  .uploadToSignedUrl('folder/cat.jpg', 'token-from-createSignedUploadUrl', file)

Retrieve public URL

A simple convenience function to get the URL for an asset in a public bucket. If you do not want to use this function, you can construct the public URL by concatenating the bucket URL with the path to the asset. This function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset.

  • The bucket needs to be set to public, either via updateBucket() or by going to Storage on supabase.com/dashboard, clicking the overflow menu on a bucket and choosing "Make public"
  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: none
  • Refer to the Storage guide on how access control works
Parameters
    path
    REQUIRED
    string

    The path and name of the file to generate the public URL for. For example folder/image.png.

    options
    Optional
    object

const { data } = supabase
  .storage
  .from('public-bucket')
  .getPublicUrl('folder/avatar1.png')