JavaScript Client Library

@supabase/supabase-js

This reference documents every object and method available in Supabase's isomorphic JavaScript library, supabase-js. You can use supabase-js to interact with your Postgres database, listen to database changes, invoke Deno Edge Functions, build login and user management functionality, and manage large files.

To convert SQL queries to supabase-js calls, use the SQL to REST API translator.

Installing

Install as package#

You can install @supabase/supabase-js via the terminal.

1
npm install @supabase/supabase-js

Install via CDN#

You can install @supabase/supabase-js via CDN links.

1
<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
2
//or
3
<script src="https://unpkg.com/@supabase/supabase-js@2"></script>

Use at runtime in Deno#

You can use supabase-js in the Deno runtime via JSR:

1
import { createClient } from 'npm:@supabase/supabase-js@2'

Enable Data API access#

supabase-js uses the Data API to query and mutate your Postgres data. You first need to grant Data API roles permissions to access your tables and functions.

In Data API integrations settings, expose the specific tables and functions you want to access. To automatically grant access for new tables and functions in public, enable Default privileges for new entities.

Alternatively, use SQL to grant the required permissions:

1
-- Before granting access to client roles, make sure RLS is enabled
2
-- and create the policies required for each role's allowed operations.
3
alter table public.your_table enable row level security;
4
-- create policy ... on public.your_table ...;
5
6
-- Grant least-privilege access to tables after RLS and policies are in place
7
grant select on public.your_table to anon;
8
grant select, insert, update, delete on public.your_table to authenticated;
9
grant all on public.your_table to service_role;
10
11
-- Grant execute on functions after verifying any table access they rely on
12
grant execute on function public.your_function to authenticated, service_role;

Initializing

Create a new client for use in the browser.

Parameters

supabaseUrlstring
The unique Supabase URL which is supplied when you create a new project in your project dashboard.
supabaseKeystring
The unique Supabase Key which is supplied when you create a new project in your project dashboard.
options
Optional
SupabaseClientOptions

1
import { createClient } from '@supabase/supabase-js'
2
3
// Create a single supabase client for interacting with your database
4
const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')

TypeScript support

supabase-js has TypeScript support for type inference, autocompletion, type-safe queries, and more.

With TypeScript, supabase-js detects things like not null constraints and generated columns. Nullable columns are typed as T | null when you select the column. Generated columns will show a type error when you insert to it.

supabase-js also detects relationships between tables. A referenced table with one-to-many relationship is typed as T[]. Likewise, a referenced table with many-to-one relationship is typed as T | null.

Generating TypeScript Types#

You can use the Supabase CLI to generate the types. You can also generate the types from the dashboard.

1
supabase gen types typescript --project-id abcdefghijklmnopqrst > database.types.ts

These types are generated from your database schema. Given a table public.movies, the generated types will look like:

1
create table public.movies (
2
  id bigint generated always as identity primary key,
3
  name text not null,
4
  data jsonb null
5
);

1
export type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[]
2
3
export interface Database {
4
  public: {
5
    Tables: {
6
      movies: {
7
        Row: {               // the data expected from .select()
8
          id: number
9
          name: string
10
          data: Json | null
11
        }
12
        Insert: {            // the data to be passed to .insert()
13
          id?: never         // generated columns must not be supplied
14
          name: string       // `not null` columns with no default must be supplied
15
          data?: Json | null // nullable columns can be omitted
16
        }
17
        Update: {            // the data to be passed to .update()
18
          id?: never
19
          name?: string      // `not null` columns are optional on .update()
20
          data?: Json | null
21
        }
22
      }
23
    }
24
  }
25
}

Using TypeScript type definitions#

You can supply the type definitions to supabase-js like so:

1
import { createClient } from '@supabase/supabase-js'
2
import { Database } from './database.types'
3
4
const supabase = createClient<Database>(
5
  process.env.SUPABASE_URL,
6
  process.env.SUPABASE_PUBLISHABLE_KEY
7
)

Helper types for Tables and Joins#

You can use the following helper types to make the generated TypeScript types easier to use.

Sometimes the generated types are not what you expect. For example, a view's column may show up as nullable when you expect it to be not null. Using type-fest, you can override the types like so:

1
export type Json = // ...
2
3
export interface Database {
4
  // ...
5
}

1
import { MergeDeep } from 'type-fest'
2
import { Database as DatabaseGenerated } from './database-generated.types'
3
export { Json } from './database-generated.types'
4
5
// Override the type for a specific column in a view:
6
export type Database = MergeDeep<
7
  DatabaseGenerated,
8
  {
9
    public: {
10
      Views: {
11
        movies_view: {
12
          Row: {
13
            // id is a primary key in public.movies, so it must be `not null`
14
            id: number
15
          }
16
        }
17
      }
18
    }
19
  }
20
>

You can also override the type of an individual successful response if needed:

1
// Partial type override allows you to only override some of the properties in your results
2
const { data } = await supabase.from('countries').select().overrideTypes<Array<{ id: string }>>()
3
// For a full replacement of the original return type use the `{ merge: false }` property as second argument
4
const { data } = await supabase
5
  .from('countries')
6
  .select()
7
  .overrideTypes<Array<{ id: string }>, { merge: false }>()
8
// Use it with `maybeSingle` or `single`
9
const { data } = await supabase.from('countries').select().single().overrideTypes<{ id: string }>()

The generated types provide shorthands for accessing tables and enums.

1
import { Database, Tables, Enums } from "./database.types.ts";
2
3
// Before 😕
4
let movie: Database['public']['Tables']['movies']['Row'] = // ...
5
6
// After 😍
7
let movie: Tables<'movies'>

Response types for complex queries#

supabase-js always returns a data object (for success), and an error object (for unsuccessful requests).

These helper types provide the result types from any query, including nested types for database joins.

Given the following schema with a relation between cities and countries, we can get the nested CountriesWithCities type:

1
create table countries (
2
  "id" serial primary key,
3
  "name" text
4
);
5
6
create table cities (
7
  "id" serial primary key,
8
  "name" text,
9
  "country_id" int references "countries"
10
);

1
import { QueryResult, QueryData, QueryError } from '@supabase/supabase-js'
2
3
const countriesWithCitiesQuery = supabase
4
  .from("countries")
5
  .select(`
6
    id,
7
    name,
8
    cities (
9
      id,
10
      name
11
    )
12
  `);
13
type CountriesWithCities = QueryData<typeof countriesWithCitiesQuery>;
14
15
const { data, error } = await countriesWithCitiesQuery;
16
if (error) throw error;
17
const countriesWithCities: CountriesWithCities = data;

delete

delete(options)

Perform a DELETE on the table or view.

By default, deleted rows are not returned. To return it, chain the call with .select() after filters.

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.

Parameters

optionsobject
Named parameters

1
const response = await supabase
2
  .from('countries')
3
  .delete()
4
  .eq('id', 1)

from

from(relation)

Perform a query on a table or a view.

Parameters

relationOne of the following options
- Option 1TableName
- Option 2ViewName

insert

insert(values, options)

Perform an INSERT into the table or view.

By default, inserted rows are not returned. To return it, chain the call with .select().

Parameters

valuesOne of the following options
The values to insert. Pass an object to insert a single row or an array to insert multiple rows.
- Option 1RejectExcessProperties
- Option 2Array<RejectExcessProperties>
optionsobject
Named parameters

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

rpc

rpc(fn, args, options)

Perform a function call.

Parameters

fnFnName
The function name to call
argsArgs
The arguments to pass to the function call
optionsobject
Named parameters

1
// For cross-schema functions where type inference fails, use overrideTypes:
2
const { data } = await supabase
3
  .schema('schema_b')
4
  .rpc('function_a', {})
5
  .overrideTypes<{ id: string; user_id: string }[]>()

schema

schema(schema)

Select a schema to query or perform an function (rpc) call.

The schema needs to be on the list of exposed schemas inside Supabase.

Parameters

schemaDynamicSchema
The schema to query

select

select(columns?, options?)

Perform a SELECT query on the table or view.

When using count with .range() or .limit(), the returned count is the total number of rows that match your filters, not the number of rows in the current page. Use this to build pagination UI.

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

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()

update

update(values, options)

Perform an UPDATE on the table or view.

By default, updated rows are not returned. To return it, chain the call with .select() after filters.

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

Parameters

valuesRejectExcessProperties
The values to update with
optionsobject
Named parameters

1
const { error } = await supabase
2
  .from('instruments')
3
  .update({ name: 'piano' })
4
  .eq('id', 1)

upsert

upsert(values, options)

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.

By default, upserted rows are not returned. To return it, chain the call with .select().

Primary keys must be included in values to use upsert.

Parameters

valuesOne of the following options
The values to upsert with. Pass an object to upsert a single row or an array to upsert multiple rows.
- Option 1RejectExcessProperties
- Option 2Array<RejectExcessProperties>
optionsobject
Named parameters

1
// Upserting a single row, overwriting based on the 'username' unique column
2
const { data, error } = await supabase
3
  .from('users')
4
  .upsert({ username: 'supabot' }, { onConflict: 'username' })
5
6
// Example response:
7
// {
8
//   data: [
9
//     { id: 4, message: 'bar', username: 'supabot' }
10
//   ],
11
//   error: null
12
// }

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.

1
const { data, error } = await supabase
2
  .from('instruments')
3
  .select('name, section_id')
4
  .eq('name', 'violin')    // Correct
5
6
const { data, error } = await supabase
7
  .from('instruments')
8
  .eq('name', 'violin')    // Incorrect
9
  .select('name, section_id')

containedBy

containedBy(column, value)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1string
- Option 2Record<string, unknown>
- Option 3Array<Row['ColumnName']>
- Option 4Array<unknown>

Return Type

this

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

contains

contains(column, value)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1string
- Option 2Record<string, unknown>
- Option 3Array<Row['ColumnName']>
- Option 4Array<unknown>

Return Type

this

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

eq

eq(column, value)

Match only rows where column is equal to value.

To check if the value of column is NULL, you should use .is() instead.

Parameters

column
The column to filter on
value
The value to filter with

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .eq('name', 'Leia')

filter

filter(column, operator, value)

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

Unlike most filters, opearator and value are used as-is and need to follow PostgREST syntax. You also need to make sure they are properly sanitized.

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

columnOne of the following options
- Option 1ColumnName
- Option 2string
operatorOne of the following options
- Option 1FilterOperator
- Option 2"not.match"
- Option 3"not.is"
- Option 4"not.eq"
- Option 5"not.neq"
- Option 6"not.gt"
- Option 7"not.gte"
- Option 8"not.lt"
- Option 9"not.lte"
- Option 10"not.like"
- Option 11"not.ilike"
- Option 12"not.isdistinct"
- Option 13"not.in"
- Option 14"not.cs"
- Option 15"not.cd"
- Option 16"not.sl"
- Option 17"not.sr"
- Option 18"not.nxl"
- Option 19"not.nxr"
- Option 20"not.adj"
- Option 21"not.ov"
- Option 22"not.fts"
- Option 23"not.plfts"
- Option 24"not.phfts"
- Option 25"not.wfts"
- Option 26"not.imatch"
- Option 27string
valueunknown

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .filter('name', 'in', '("Han","Yoda")')

gt

gt(column, value)

Match only rows where column is greater than value.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1Row['ColumnName']
- Option 2unknown

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .gt('id', 2)

gte

gte(column, value)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1Row['ColumnName']
- Option 2unknown

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .gte('id', 2)

ilike

ilike(column, pattern)

Match only rows where column matches pattern case-insensitively.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
patternstring

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .ilike('name', '%lu%')

ilikeAllOf

ilikeAllOf(column, patterns)

Match only rows where column matches all of patterns case-insensitively.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
patternsArray<string>

Return Type

this

ilikeAnyOf

ilikeAnyOf(column, patterns)

Match only rows where column matches any of patterns case-insensitively.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
patternsArray<string>

Return Type

this

in

in(column, values)

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

Parameters

columnColumnName
The column to filter on
valuesArray
The values array to filter with

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .in('name', ['Leia', 'Han'])

is

is(column, value)

Match only rows where column IS value.

For non-boolean columns, this is only relevant for checking if the value of column is NULL by setting value to null.

For boolean columns, you can also set value to true or false and it will behave the same way as .eq().

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1null
- Option 2boolean

Return Type

this

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

like

like(column, pattern)

Match only rows where column matches pattern case-sensitively.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
patternstring

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .like('name', '%Lu%')

likeAllOf

likeAllOf(column, patterns)

Match only rows where column matches all of patterns case-sensitively.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
patternsArray<string>

Return Type

this

likeAnyOf

likeAnyOf(column, patterns)

Match only rows where column matches any of patterns case-sensitively.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
patternsArray<string>

Return Type

this

lt

lt(column, value)

Match only rows where column is less than value.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1Row['ColumnName']
- Option 2unknown

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .lt('id', 2)

lte

lte(column, value)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1Row['ColumnName']
- Option 2unknown

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .lte('id', 2)

match

match(query)

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

Parameters

queryOne of the following options
- Option 1Record<ColumnName, Row['ColumnName']>
- Option 2Record<string, unknown>

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .match({ id: 2, name: 'Leia' })

neq

neq(column, value)

Match only rows where column is not equal to value.

This filter does not include rows where column is NULL. To match null values, use .is(column, null) instead.

Parameters

column
The column to filter on
value
The value to filter with

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .neq('name', 'Leia')

not

not(column, operator, value)

Match only rows which doesn't satisfy the filter.

Unlike most filters, opearator and value are used as-is and need to follow PostgREST syntax. You also need to make sure they are properly sanitized.

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

columnOne of the following options
- Option 1ColumnName
- Option 2string
operatorOne of the following options
- Option 1"is"
- Option 2FilterOperator
- Option 3string
valueOne of the following options
- Option 1null
- Option 2Row['ColumnName']
- Option 3unknown

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

or

or(filters, options)

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

Unlike most filters, filters is used as-is and needs to follow PostgREST syntax. You also need to make sure it's properly sanitized.

It's currently not possible to do an .or() filter across multiple tables.

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

filtersstring
The filters to use, following PostgREST syntax
optionsobject
Named parameters

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .or('id.eq.2,name.eq.Han')

overlaps

overlaps(column, value)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
valueOne of the following options
- Option 1string
- Option 2Array<Row['ColumnName']>
- Option 3Array<unknown>

Return Type

this

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

rangeAdjacent

rangeAdjacent(column, 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

columnOne of the following options
- Option 1ColumnName
- Option 2string
rangestring

Return Type

this

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

rangeGt

rangeGt(column, range)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
rangestring

Return Type

this

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

rangeGte

rangeGte(column, 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

columnOne of the following options
- Option 1ColumnName
- Option 2string
rangestring

Return Type

this

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

rangeLt

rangeLt(column, range)

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

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
rangestring

Return Type

this

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

rangeLte

rangeLte(column, 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

columnOne of the following options
- Option 1ColumnName
- Option 2string
rangestring

Return Type

this

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

textSearch

textSearch(column, query, options?)

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.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
querystring
options
Optional
object

Return Type

this

1
const result = await supabase
2
  .from("texts")
3
  .select("content")
4
  .textSearch("content", `'eggs' & 'ham'`, {
5
    config: "english",
6
  });

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

abortSignal

abortSignal(signal)

Set the AbortSignal for the fetch request.

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

Parameters

signalAbortSignal
The AbortSignal to use for the fetch request

Return Type

this

1
const ac = new AbortController()
2
3
const { data, error } = await supabase
4
  .from('very_big_table')
5
  .select()
6
  .abortSignal(ac.signal)
7
8
// Abort the request after 100 ms
9
setTimeout(() => ac.abort(), 100)

csv

csv()

Return data as a string in CSV format.

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .csv()

explain

explain(options)

Return data as the EXPLAIN plan for the query.

You need to enable the db_plan_enabled setting before using this method.

Parameters

optionsobject
Named parameters

Return Type

One of the following options

Option 1PostgrestBuilder
Option 2PostgrestBuilder

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .explain()

geojson

geojson()

Return data as an object in GeoJSON format.

limit

limit(rows, options)

Limit the query result by rows.

Parameters

rowsnumber
The maximum number of rows to return
optionsobject
Named parameters

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .limit(1)

maxAffected

maxAffected(rows)

Set the maximum number of rows that can be affected by the query. Only available in PostgREST v13+ and only works with PATCH and DELETE methods.

Parameters

rowsnumber
The maximum number of rows that can be affected

maybeSingle

maybeSingle()

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

Query result must be zero or one row (e.g. using .limit(1)), otherwise this returns an error.

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .eq('name', 'Katniss')
5
  .maybeSingle()

order

order(column, options?)

Order the query result by column.

You can call this method multiple times to order by multiple columns.

You can order referenced tables, but it only affects the ordering of the parent table if you use !inner in the query.

Parameters

columnOne of the following options
- Option 1ColumnName
- Option 2string
options
Optional
object

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('id, name')
4
  .order('id', { ascending: false })

overrideTypes

overrideTypes()

Override the type of the returned data field in the response.

1
// Merge with existing types (default behavior)
2
const query = supabase
3
  .from('users')
4
  .select()
5
  .overrideTypes<{ custom_field: string }>()
6
7
// Replace existing types completely
8
const replaceQuery = supabase
9
  .from('users')
10
  .select()
11
  .overrideTypes<{ id: number; name: string }, { merge: false }>()

range

range(from, to, options)

Limit the query result by starting at an offset from and ending at the offset 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

fromnumber
The starting index from which to limit the result
tonumber
The last index to which to limit the result
optionsobject
Named parameters

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .range(0, 1)

retry

retry(enabled)

Parameters

enabledboolean
Whether to enable retries for this request

Return Type

this

1
// Disable retries for a specific query
2
const { data, error } = await supabase
3
  .from('users')
4
  .select()
5
  .retry(false)

returns

returns()

Override the type of the returned data.

rollback

rollback()

Dry-run this request: execute the query but discard the changes.

Server-side, PostgREST runs the query inside a transaction and rolls it back instead of committing. The response still contains the data that would have been returned — RETURNING clauses execute and RLS, triggers, and constraints are all evaluated — but no row is actually inserted, updated, or deleted.

This affects only the single request it is chained to. The JS caller has no handle on the transaction: supabase-js does not group multiple queries into one transaction. For multi-statement transactional logic, use a database function (supabase.rpc(...)).

Sets the Prefer: tx=rollback header. See PostgREST's docs on transaction preferences for the underlying mechanism.

Return Type

this

1
const { data, error } = await supabase
2
  .from('countries')
3
  .insert({ name: 'France' })
4
  .select()
5
  .rollback()
6
// `data` shows what would have been inserted; nothing is saved.

select

select(columns?)

Perform a SELECT on the query result.

By default, .insert(), .update(), .upsert(), and .delete() do not return modified rows. By calling this method, modified rows are returned in data.

Parameters

columns
Optional
Query
The columns to retrieve, separated by commas

1
const { data, error } = await supabase
2
  .from('characters')
3
  .upsert({ id: 1, name: 'Han Solo' })
4
  .select()

setHeader

setHeader(name, value)

Set an HTTP header on this single PostgREST request, overriding any header with the same name set on the client.

This is an advanced escape hatch for one-off needs (passing a custom Authorization for a single query, attaching a tracing header, etc.). Most callers do not need it: configure client-wide headers via the headers option when constructing the client, and authentication via Supabase Auth.

Parameters

namestring
HTTP header name
valuestring
HTTP header value

Return Type

this

single

single()

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

Query result must be one row (e.g. using .limit(1)), otherwise this returns an error.

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .limit(1)
5
  .single()

stripNulls

stripNulls()

Strip null values from the response data. Properties with null values will be omitted from the returned JSON objects.

Requires PostgREST 11.2.0+.

https://docs.postgrest.org/en/stable/references/api/resource\_representation.html#stripped-nulls

Return Type

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .stripNulls()

throwOnError

throwOnError()

If there's an error with the query, throwOnError will reject the promise by throwing the error instead of returning it as part of a successful response.

https://github.com/supabase/supabase-js/issues/92

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.

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(supabase_url, publishable_key)

dispose

dispose()

Tears down the client's background work: stops the auto-refresh interval, removes the visibilitychange listener, closes the cross-tab BroadcastChannel, and clears registered onAuthStateChange subscribers.

Call this from cleanup hooks when the client is being replaced before its JS realm is destroyed. React Strict Mode and HMR are the common cases. Any in-flight fetch calls continue to completion and may still write to storage; dispose doesn't abort them or erase storage.

Lifecycle caveat: because in-flight refreshes are not aborted, a disposed instance can still persist a rotated session to storage after dispose() returns. A subsequent createClient against the same storageKey will pick up that session on its next read. If you need strict isolation between client lifecycles, await any pending auth operation before calling dispose() (or change the storageKey for the replacement client).

Safe to call repeatedly.

Return Type

Promise<void>

1
useEffect(() => {
2
  const client = createClient(...)
3
  return () => { client.auth.dispose() }
4
}, [])

exchangeCodeForSession

exchangeCodeForSession(authCode)

Used when flowType is set to pkce in client options.

Parameters

authCodestring

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

getClaims

getClaims(jwt?, options)

Extracts the JWT claims present in the access token by first verifying the JWT against the server's JSON Web Key Set endpoint /.well-known/jwks.json which is often cached, resulting in significantly faster responses. Prefer this method over #getUser which always sends a request to the Auth server for each JWT.

If the project is not using an asymmetric JWT signing key (like ECC or RSA) it always sends a request to the Auth server (similar to #getUser) to verify the JWT.

Parses the user's access token as a JSON Web Token (JWT) and returns its components if valid and not expired.
If your project is using asymmetric JWT signing keys, then the verification is done locally usually without a network request using the WebCrypto API.
A network request is sent to your project's JWT signing key discovery endpoint https://project-id.supabase.co/auth/v1/.well-known/jwks.json, which is cached locally. If your environment is ephemeral, such as a Lambda function that is destroyed after every request, a network request will be sent for each new invocation. Supabase provides a network-edge cache providing fast responses for these situations.
If the user's access token is about to expire when calling this function, the user's session will first be refreshed before validating the JWT.
If your project is using a symmetric secret to sign the JWT, it always sends a request similar to getUser() to validate the JWT at the server before returning the decoded token. This is also used if the WebCrypto API is not available in the environment. Make sure you polyfill it in such situations.
The returned claims can be customized per project using the Custom Access Token Hook.

Parameters

jwt
Optional
string
An optional specific JWT you wish to verify, not the one you can obtain from #getSession.
optionsobject
Various additional options that allow you to customize the behavior of this method.

Return Type

Promise<One of the following options>

Option 1object
Option 2object
Option 3object

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

getSession

getSession()

Returns the session, refreshing it if necessary.

The session returned can be null if the session is not detected which can happen in the event a user is not signed-in or has logged out.

IMPORTANT: This method loads values directly from the storage attached to the client. If that storage is based on request cookies for example, the values in it may not be authentic and therefore it's strongly advised against using this method and its results in such circumstances. A warning will be emitted if this is detected. Use #getUser() instead.

Since the introduction of asymmetric JWT signing keys, this method is considered low-level and we encourage you to use getClaims() or getUser() instead.
Retrieves the current user session from the storage medium (local storage, cookies).
The session contains an access token (signed JWT), a refresh token and the user object.
If the session's access token is expired or is about to expire, this method will use the refresh token to refresh the session.
When using in a browser, or you've called startAutoRefresh() in your environment (React Native, etc.) this function always returns a valid access token without refreshing the session itself, as this is done in the background. This function returns very fast.
IMPORTANT SECURITY NOTICE: If using an insecure storage medium, such as cookies or request headers, the user object returned by this function must not be trusted. Always verify the JWT using getClaims() or your own JWT verification library to securely establish the user's identity and access. You can also use getUser() to fetch the user object directly from the Auth server for this purpose.
Cross-tab refresh races are handled by the GoTrue server (the rotated token from the first tab is returned to subsequent tabs via the parent-of-active mechanism), so no client-side serialization is needed.

Return Type

Promise<One of the following options>

Option 1object
Option 2object
Option 3object

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

getUser

getUser(jwt?)

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.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

getUserIdentities

getUserIdentities()

Gets all the identities linked to a user.

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

initialize

initialize()

Initialize the auth client by loading the session from storage or detecting it from the URL after an OAuth, magic-link, or password-recovery redirect.

Most callers do not need to invoke this directly. The client calls it automatically during construction, and to react to sign-in events (including post-redirect events) you should subscribe to onAuthStateChange rather than awaiting initialize().

You only need to call it manually when you have opted out of the automatic call by passing skipAutoInitialize: true — for example, in an SSR context where you need to control initialization timing. In that case, awaiting initialize() returns the resolved session result (or any error encountered while detecting it from the URL).

Return Type

Promise<InitializeResult>

linkIdentity

linkIdentity(credentials)

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.

Parameters

credentialsOne of the following options
- Option 1SignInWithOAuthCredentials
- Option 2SignInWithIdTokenCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.linkIdentity({
2
  provider: 'github'
3
})

onAuthStateChange

onAuthStateChange(callback)

Receive a notification every time an auth event happens. Safe to use without an async function as callback.

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.
Callbacks can be async and can safely call other Supabase auth methods (getUser, setSession, etc.) from inside the callback.
Keep callbacks quick. Events are awaited in order, so a slow callback delays subsequent events to subscribers in this tab.
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

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

Return Type

object

1
const { data } = supabase.auth.onAuthStateChange((event, session) => {
2
  console.log(event, session)
3
4
  if (event === 'INITIAL_SESSION') {
5
    // handle initial session
6
  } else if (event === 'SIGNED_IN') {
7
    // handle sign in event
8
  } else if (event === 'SIGNED_OUT') {
9
    // handle sign out event
10
  } else if (event === 'PASSWORD_RECOVERY') {
11
    // handle password recovery event
12
  } else if (event === 'TOKEN_REFRESHED') {
13
    // handle token refreshed event
14
  } else if (event === 'USER_UPDATED') {
15
    // handle user updated event
16
  }
17
})
18
19
// call unsubscribe to remove the callback
20
data.subscription.unsubscribe()

reauthenticate

reauthenticate()

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.
After receiving the OTP, include it as the nonce in your updateUser() call to finalize the password change.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

refreshSession

refreshSession(currentSession?)

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.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

registerPasskey

registerPasskey(credentials?)

Fetches registration challenge from server
Prompts user via navigator.credentials.create()
Verifies credential with server

Requires an active session. Requires auth.experimental.passkey: true.

Parameters

credentials
Optional
RegisterPasskeyCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

resend

resend(credentials)

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(note: For existing users signing in with OTP, you should use signInWithOtp() again to resend the OTP).
You can specify a redirect url when you resend an email link using the emailRedirectTo option.

Parameters

credentialsOne of the following options
- Option 1object
- Option 2object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

resetPasswordForEmail

resetPasswordForEmail(email, options)

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 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():

1
const { data, error } = await supabase.auth.updateUser({
2
  password: new_password
3
})

Parameters

emailstring
The email address of the user.
optionsobject

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

setSession

setSession(currentSession)

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.

Parameters

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

signInAnonymously

signInAnonymously(credentials?)

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.signInAnonymously({
2
  options: {
3
    captchaToken
4
  }
5
});

signInWithIdToken

signInWithIdToken(credentials)

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

Use an ID token to sign in.
Especially useful when implementing sign in using native platform dialogs in mobile or desktop apps using Sign in with Apple or Sign in with Google on iOS and Android.
You can also use Google's One Tap and Automatic sign-in via this API.

Parameters

credentialsSignInWithIdTokenCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

signInWithOAuth

signInWithOAuth(credentials)

This method is used for signing in using Social Login (OAuth) providers.
It works by redirecting your application to the provider's authorization screen, before bringing back the user to your app.

Parameters

credentialsSignInWithOAuthCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

signInWithOtp

signInWithOtp(credentials)

If the {{ .ConfirmationURL }} variable is specified in the email template, a magiclink will be sent. If the {{ .Token }} variable is specified in the email template, an OTP will be sent. If you're using phone sign-ins, only an OTP will be sent. You won't be able to send a magiclink for phone sign-ins.

Be aware that you may get back an error message that will not distinguish between the cases where the account does not exist or, that the account can only be accessed via social login.

Do note that you will need to configure a Whatsapp sender on Twilio if you are using phone sign in with the 'whatsapp' channel. The whatsapp channel is not supported on other providers at this time. This method supports PKCE when an email is passed.

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.

Parameters

credentialsOne of the following options
- Option 1object
- Option 2object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

signInWithPasskey

signInWithPasskey(credentials?)

Fetches authentication challenge from server
Prompts user via navigator.credentials.get()
Verifies credential with server and creates session

Requires auth.experimental.passkey: true.

Parameters

credentials
Optional
SignInWithPasskeyCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

signInWithPassword

signInWithPassword(credentials)

Be aware that you may get back an error message that will not distinguish between the cases where the account does not exist or that the email/phone and password combination is wrong or that the account can only be accessed via social login.

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

Parameters

credentialsSignInWithPasswordCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

signInWithSSO

signInWithSSO(params)

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.

You can use it by providing a SSO domain. Typically you can extract this domain by asking users for their email address. If this domain is registered on the Auth instance the redirect will use that organization's currently active SSO Identity Provider for the login.

If you have built an organization-specific login page, you can use the organization's SSO Identity Provider UUID directly instead.

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

paramsOne of the following options
- Option 1object
- Option 2object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
// You can extract the user's email domain and use it to trigger the
2
  // authentication flow with the correct identity provider.
3
4
  const { data, error } = await supabase.auth.signInWithSSO({
5
    domain: 'company.com'
6
  })
7
8
  if (data?.url) {
9
    // redirect the user to the identity provider's authentication flow
10
    window.location.href = data.url
11
  }

signInWithWeb3

signInWithWeb3(credentials)

Signs in a user by verifying a message signed by the user's private key. Supports Ethereum (via Sign-In-With-Ethereum) & Solana (Sign-In-With-Solana) standards, both of which derive from the EIP-4361 standard With slight variation on Solana's side.

Uses a Web3 (Ethereum, Solana) wallet to sign a user in.
Read up on the potential for abuse before using it.

Parameters

credentialsOne of the following options
- Option 1One of the following options
  Option 1object
  Option 2object
- Option 2One of the following options
  Option 1object
  Option 2object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
// uses window.ethereum for the wallet
2
  const { data, error } = await supabase.auth.signInWithWeb3({
3
    chain: 'ethereum',
4
    statement: 'I accept the Terms of Service at https://example.com/tos'
5
  })
6
7
  // uses window.solana for the wallet
8
  const { data, error } = await supabase.auth.signInWithWeb3({
9
    chain: 'solana',
10
    statement: 'I accept the Terms of Service at https://example.com/tos'
11
  })

signOut

signOut(options)

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.

For server-side management, you can revoke all refresh tokens for a user by passing a user's JWT through to auth.api.signOut(JWT: string). There is no way to revoke a user's access token jwt until it expires. It is recommended to set a shorter expiry on the jwt for this reason.

If using others scope, no SIGNED_OUT event is fired!

Warning: the default scope is 'global'. This signs the user out of every device they are currently signed in on, not just the current tab/session. If you only want to sign the user out of the current session (the behavior most other auth libraries default to), pass { scope: 'local' } explicitly.

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 the user on every device they are signed in on (not just the current one). Pass { scope: 'local' } to only sign out the current session. This is usually what apps want on a "Sign out" button, especially when users sign in from multiple devices and do not expect signing out of one to terminate the others.
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

optionsSignOut

Return Type

Promise<object>

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

signUp

signUp(credentials)

Creates a new user.

Be aware that if a user account exists in the system you may get back an error message that attempts to hide this information from the user. This method has support for PKCE via email signups. The PKCE flow cannot be used when autoconfirm is enabled.

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

credentialsSignUpWithPasswordCredentials

Return Type

Promise<One of the following options>

Option 1object
Option 2object

startAutoRefresh

startAutoRefresh()

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.

If you set the GoTrueClientOptions#autoRefreshToken you don't need to call this function, it will be called for you.

On browsers the refresh process works only when the tab/window is in the foreground to conserve resources as well as prevent race conditions and flooding auth with requests. If you call this method any managed visibility change callback will be removed and you must manage visibility changes on your own.

On non-browser platforms the refresh process works continuously in the background, which may not be desirable. You should hook into your platform's foreground indication mechanism and call these methods appropriately to conserve resources.

#stopAutoRefresh

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.

Return Type

Promise<void>

1
import { AppState } from 'react-native'
2
3
// make sure you register this only once!
4
AppState.addEventListener('change', (state) => {
5
  if (state === 'active') {
6
    supabase.auth.startAutoRefresh()
7
  } else {
8
    supabase.auth.stopAutoRefresh()
9
  }
10
})

stopAutoRefresh

stopAutoRefresh()

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

If you call this method any managed visibility change callback will be removed and you must manage visibility changes on your own.

See #startAutoRefresh for more details.

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.

Return Type

Promise<void>

1
import { AppState } from 'react-native'
2
3
// make sure you register this only once!
4
AppState.addEventListener('change', (state) => {
5
  if (state === 'active') {
6
    supabase.auth.startAutoRefresh()
7
  } else {
8
    supabase.auth.stopAutoRefresh()
9
  }
10
})

unlinkIdentity

unlinkIdentity(identity)

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

identityUserIdentity

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
// retrieve all identities linked to a user
2
const identities = await supabase.auth.getUserIdentities()
3
4
// find the google identity
5
const googleIdentity = identities.find(
6
  identity => identity.provider === 'google'
7
)
8
9
// unlink the google identity
10
const { error } = await supabase.auth.unlinkIdentity(googleIdentity)

updateUser

updateUser(attributes, options)

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

attributesUserAttributes
optionsobject

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.updateUser({
2
  email: 'new@email.com'
3
})

verifyOtp

verifyOtp(params)

The verifyOtp method takes in different verification types.
If a phone number is used, the type can either be:
1. sms – Used when verifying a one-time password (OTP) sent via SMS during sign-up or sign-in.
2. phone_change – Used when verifying an OTP sent to a new phone number during a phone number update process.
If an email address is used, the type can be one of the following (note: signup and magiclink types are deprecated):
1. email – Used when verifying an OTP sent to the user's email during sign-up or sign-in.
2. recovery – Used when verifying an OTP sent for account recovery, typically after a password reset request.
3. invite – Used when verifying an OTP sent as part of an invitation to join a project or organization.
4. email_change – Used when verifying an OTP sent to a new email address during an email update process.
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 for the PKCE flow for Server Side Auth. Read the Password-based Auth guide for more details.

Parameters

paramsOne of the following options
- Option 1VerifyMobileOtpParams
- Option 2VerifyEmailOtpParams
- Option 3VerifyTokenHashParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

Overview

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

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(supabase_url, secret_key, {
4
  auth: {
5
    autoRefreshToken: false,
6
    persistSession: false
7
  }
8
})
9
10
// Access auth admin api
11
const adminAuthClient = supabase.auth.admin

createProvider

createProvider(params)

Creates a new custom OIDC/OAuth provider.

For OIDC providers, the server fetches and validates the OpenID Connect discovery document from the issuer's well-known endpoint (or the provided discovery_url) at creation time. This may return a validation error (error_code: "validation_failed") if the discovery document is unreachable, not valid JSON, missing required fields, or if the issuer in the document does not match the expected issuer.

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

Parameters

paramsCreateCustomProviderParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

createUser

createUser(attributes)

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

attributesAdminUserAttributes

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.createUser({
2
  email: 'user@email.com',
3
  password: 'password',
4
  user_metadata: { name: 'Yoda' }
5
})

deleteFactor

deleteFactor(params)

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

Parameters

paramsAuthMFAAdminDeleteFactorParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

deleteProvider

deleteProvider(identifier)

Deletes a custom provider.

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

Parameters

identifierstring

Return Type

Promise<object>

deleteUser

deleteUser(id, shouldSoftDelete)

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

idstring
The user id you want to remove.
shouldSoftDeleteboolean
If true, then the user will be soft-deleted from the auth schema. Soft deletion allows user identification from the hashed user ID but is not reversible. Defaults to false for backward compatibility.

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

generateLink

generateLink(params)

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

paramsOne of the following options
- Option 1GenerateSignupLinkParams
- Option 2GenerateInviteOrMagiclinkParams
- Option 3GenerateRecoveryLinkParams
- Option 4GenerateEmailChangeLinkParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

getProvider

getProvider(identifier)

Gets details of a specific custom provider by identifier.

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

Parameters

identifierstring

Return Type

Promise<One of the following options>

Option 1object
Option 2object

getUserById

getUserById(uid)

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

uidstring
The user's unique identifier

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

inviteUserByEmail

inviteUserByEmail(email, options)

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.

Parameters

emailstring
The email address of the user.
optionsobject
Additional options to be included when inviting.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.inviteUserByEmail('email@example.com')

listFactors

listFactors(params)

Lists all factors associated to a user.

Parameters

paramsAuthMFAAdminListFactorsParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

listProviders

listProviders(params?)

Lists all custom providers with optional type filter.

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

Parameters

params
Optional
ListCustomProvidersParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

listUsers

listUsers(params?)

Get a list of users.

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

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.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

signOut

signOut(jwt, scope)

Removes a logged-in session.

Parameters

jwtstring
A valid, logged-in JWT.
scopeOne of the following options
The logout sope.
- Option 1"global"
- Option 2"local"
- Option 3"others"

Return Type

Promise<object>

updateProvider

updateProvider(identifier, params)

Updates an existing custom provider.

When issuer or discovery_url is changed on an OIDC provider, the server re-fetches and validates the discovery document before persisting. This may return a validation error (error_code: "validation_failed") if the discovery document is unreachable, invalid, or the issuer does not match.

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

Parameters

identifierstring
paramsUpdateCustomProviderParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

updateUserById

updateUserById(uid, attributes)

Updates the user data. Changes are applied directly without confirmation flows.

Important: This is a server-side operation and does not trigger client-side onAuthStateChange listeners. The admin API has no connection to client state.

To sync changes to the client after calling this method:

On the client, call supabase.auth.refreshSession() to fetch the updated user data
This will trigger the TOKEN_REFRESHED event and notify all listeners

Parameters

uidstring
The user's unique identifier
attributesAdminUserAttributes
The data you want to update.

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
// Server-side (Edge Function)
2
const { data, error } = await supabase.auth.admin.updateUserById(
3
  userId,
4
  { user_metadata: { preferences: { theme: 'dark' } } }
5
)
6
7
// Client-side (to sync the changes)
8
const { data, error } = await supabase.auth.refreshSession()
9
// onAuthStateChange listeners will now be notified with updated user

Auth MFA

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.

Learn more about implementing MFA in your application in the MFA guide.

challenge

challenge(params)

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.

Parameters

paramsOne of the following options
- Option 1MFAChallengeParamsBase
- Option 2MFAChallengePhoneParams
- Option 3MFAChallengeWebauthnParams
- Option 4MFAChallengeTOTPParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

challengeAndVerify

challengeAndVerify(params)

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.

Parameters

paramsMFAChallengeAndVerifyTOTPParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

enroll

enroll(params)

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

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

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:

1
<Image src={data.totp.qr_code} alt={data.totp.uri} layout="fill"></Image>

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.

Parameters

paramsOne of the following options
- Option 1MFAEnrollTOTPParams
- Option 2MFAEnrollPhoneParams
- Option 3MFAEnrollParamsBase
- Option 4MFAEnrollWebauthnParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.enroll({
2
  factorType: 'totp',
3
  friendlyName: 'your_friendly_name'
4
})
5
6
// Use the id to create a challenge.
7
// The challenge can be verified by entering the code generated from the authenticator app.
8
// The code will be generated upon scanning the qr_code or entering the secret into the authenticator app.
9
const { id, type, totp: { qr_code, secret, uri }, friendly_name } = data
10
const challenge = await supabase.auth.mfa.challenge({ factorId: id });

getAuthenticatorAssuranceLevel

getAuthenticatorAssuranceLevel(jwt?)

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

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

When called without a JWT parameter, this method is fairly quick (microseconds) and rarely uses the network. When a JWT is provided (useful in server-side environments like Edge Functions where no session is stored), this method will make a network request to validate the user and fetch their MFA factors.

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.
An optional jwt parameter can be passed to check the AAL level of a specific JWT instead of the current session.

Parameters

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

listFactors

listFactors()

Returns the list of MFA factors enabled for this user.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

unenroll

unenroll(params)

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

Parameters

paramsMFAUnenrollParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

verify

verify(params)

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.

Parameters

paramsOne of the following options
- Option 1MFAVerifyTOTPParams
- Option 2MFAVerifyPhoneParams
- Option 3MFAVerifyWebauthnParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

Auth Passkey

This section contains methods for WebAuthn passkey registration, authentication, and management. Methods are invoked behind the supabase.auth.passkey namespace.

Passkey support is an experimental feature. Enable it when creating the client:

delete

delete(params)

Deletes a passkey for the currently signed-in user.

Parameters

paramsPasskeyDeleteParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

list

list()

Lists all passkeys registered for the currently signed-in user.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

startAuthentication

startAuthentication(params?)

Starts the passkey authentication ceremony. Fetches an authentication challenge and credential request options from the server. Used as the first step of a two-step sign-in flow when the caller wants to handle navigator.credentials.get() themselves.

Parameters

params
Optional
StartPasskeyAuthenticationParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

startRegistration

startRegistration()

Starts the passkey registration ceremony. Fetches a registration challenge and credential creation options from the server. Used as the first step of a two-step registration flow when the caller wants to handle navigator.credentials.create() themselves.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

update

update(params)

Updates a passkey's friendly name.

Parameters

paramsPasskeyUpdateParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

verifyAuthentication

verifyAuthentication(params)

Verifies a passkey authentication credential against a previously issued challenge. Used as the second step of a two-step sign-in flow.

Parameters

paramsVerifyPasskeyAuthenticationParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

verifyRegistration

verifyRegistration(params)

Verifies a passkey registration credential against a previously issued challenge. Used as the second step of a two-step registration flow.

Parameters

paramsVerifyPasskeyRegistrationParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

OAuth Admin

The OAuth Admin API allows you to manage OAuth clients programmatically. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth. These functions should only be called on a server. Never expose your secret key in the browser.

createClient

createClient(params)

Creates a new OAuth client. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

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

Parameters

paramsCreateOAuthClientParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

deleteClient

deleteClient(clientId)

Deletes an OAuth client. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

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

Parameters

clientIdstring

Return Type

Promise<object>

getClient

getClient(clientId)

Gets details of a specific OAuth client. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

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

Parameters

clientIdstring

Return Type

Promise<One of the following options>

Option 1object
Option 2object

listClients

listClients(params?)

Lists all OAuth clients with optional pagination. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

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

Parameters

params
Optional
PageParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

regenerateClientSecret

regenerateClientSecret(clientId)

Regenerates the secret for an OAuth client. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

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

Parameters

clientIdstring

Return Type

Promise<One of the following options>

Option 1object
Option 2object

updateClient

updateClient(clientId, params)

Updates an existing OAuth client. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

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

Parameters

clientIdstring
paramsUpdateOAuthClientParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

OAuth Server

The OAuth Server API allows you to build custom OAuth consent screens for your application. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

approveAuthorization

approveAuthorization(authorizationId, options?)

Approves an OAuth authorization request. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

After approval, the user's consent is stored and an authorization code is generated. The response contains a complete redirect URL with the authorization code and state.

Parameters

authorizationIdstring
The authorization ID to approve
options
Optional
object
Optional parameters

Return Type

Promise<One of the following options>

Option 1object
Option 2object

denyAuthorization

denyAuthorization(authorizationId, options?)

Denies an OAuth authorization request. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

After denial, the response contains a redirect URL with an OAuth error (access_denied) to inform the OAuth client that the user rejected the request.

Parameters

authorizationIdstring
The authorization ID to deny
options
Optional
object
Optional parameters

Return Type

Promise<One of the following options>

Option 1object
Option 2object

getAuthorizationDetails

getAuthorizationDetails(authorizationId)

Retrieves details about an OAuth authorization request. Used to display consent information to the user. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

This method returns one of two response types:

OAuthAuthorizationDetails: User needs to consent - show consent page with client info
OAuthRedirect: User already consented - redirect immediately to the OAuth client

Use type narrowing to distinguish between the responses:

1
if ('authorization_id' in data) {
2
  // Show consent page
3
} else {
4
  // Redirect to data.redirect_url
5
}

Parameters

authorizationIdstring
The authorization ID from the authorization request

Return Type

Promise<One of the following options>

Option 1object
Option 2object

listGrants

listGrants()

Lists all OAuth grants that the authenticated user has authorized. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

revokeGrant

revokeGrant(options)

Revokes a user's OAuth grant for a specific client. Only relevant when the OAuth 2.1 server is enabled in Supabase Auth.

Revocation marks consent as revoked, deletes active sessions for that OAuth client, and invalidates associated refresh tokens.

Parameters

optionsobject
Revocation options

Return Type

Promise<One of the following options>

Option 1object
Option 2object

Passkey admin

Contains passkey administration methods. Requires a secret key.

deletePasskey

deletePasskey(params)

Deletes a specific passkey for a specific user.

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

Parameters

paramsAuthPasskeyAdminDeleteParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

listPasskeys

listPasskeys(params)

Lists all passkeys registered for a specific user.

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

Parameters

paramsAuthPasskeyAdminListParams

Return Type

Promise<One of the following options>

Option 1object
Option 2object

corsHeaders

Default CORS headers for Supabase Edge Functions.

Includes all headers sent by Supabase client libraries and allows all standard HTTP methods. Use this for simple CORS configurations with wildcard origin.

1
import { corsHeaders } from '@supabase/supabase-js/cors'
2
3
Deno.serve(async (req) => {
4
  if (req.method === 'OPTIONS') {
5
    return new Response('ok', { headers: corsHeaders })
6
  }
7
8
  return new Response(
9
    JSON.stringify({ data: 'Hello' }),
10
    { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
11
  )
12
})

invoke

invoke(functionName, options)

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

Parameters

functionNamestring
The name of the Function to invoke.
optionsFunctionInvokeOptions
Options for invoking the Function.

Return Type

Promise<One of the following options>

Option 1FunctionsResponseSuccess
Option 2FunctionsResponseFailure

1
const { data, error } = await functions.invoke('hello-world', {
2
  body: { name: 'Ada' },
3
})

setAuth

setAuth(token)

Updates the authorization header

Parameters

tokenstring
the new jwt token sent in the authorisation header

Return Type

void

1
functions.setAuth(session.access_token)

channel

channel(topic, params)

Creates (or reuses) a RealtimeChannel for the provided topic.

Topics are automatically prefixed with realtime: to match the Realtime service. If a channel with the same topic already exists it will be returned instead of creating a duplicate connection.

Parameters

topicstring
paramsRealtimeChannelOptions

connect

connect()

Connects the socket, unless already connected.

Return Type

void

connectionState

connectionState()

Returns the current state of the socket.

disconnect

disconnect(code?, reason?)

Disconnects the socket.

Parameters

code
Optional
number
A numeric status code to send on disconnect.
reason
Optional
string
A custom reason for the disconnect.

Return Type

Promise<One of the following options>

Option 1"ok"
Option 2"timeout"

endpointURL

endpointURL()

Returns the URL of the websocket.

Return Type

string

getChannels

getChannels()

Returns all created channels

Return Type

Array<RealtimeChannel>

getWebSocketConstructor

getWebSocketConstructor()

Returns the best available WebSocket constructor for the current runtime.

Return Type

function

1
try {
2
  const WS = WebSocketFactory.getWebSocketConstructor()
3
  const socket = new WS('wss://example.com/socket')
4
} catch (error) {
5
  console.error('WebSocket not available in this environment.', error)
6
}

httpSend

httpSend(event, payload, opts)

Sends a broadcast message explicitly via REST API.

This method always uses the REST API endpoint regardless of WebSocket connection state. Useful when you want to guarantee REST delivery or when gradually migrating from implicit REST fallback.

Payloads that are ArrayBuffer or ArrayBufferView (e.g. Uint8Array) are sent as application/octet-stream; all other payloads are JSON-encoded.

Parameters

eventstring
The name of the broadcast event
payloadany
Payload to be sent (required)
optsobject
Options including timeout

Return Type

Promise<One of the following options>

Option 1object
Option 2object

isConnected

isConnected()

Returns true is the connection is open.

Return Type

boolean

isConnecting

isConnecting()

Returns true if the connection is currently connecting.

Return Type

boolean

isDisconnecting

isDisconnecting()

Returns true if the connection is currently disconnecting.

Return Type

boolean

isWebSocketSupported

isWebSocketSupported()

Detects whether the runtime can establish WebSocket connections.

Return Type

boolean

1
if (!WebSocketFactory.isWebSocketSupported()) {
2
  console.error('WebSockets are required for this script.')
3
  process.exitCode = 1
4
}

log

log(kind, msg, data?)

Logs the message.

For customized logging, this.logger can be overridden in Client constructor.

Parameters

kindstring
msgstring
data
Optional
any

Return Type

void

on

on(type, filter, callback)

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

typeOne of the following options
- Option 1"presence"
- Option 2"postgres_changes"
- Option 3"broadcast"
- Option 4"system"
filterOne of the following options
- Option 1object
- Option 2object
- Option 3object
- Option 4object
- Option 5RealtimePostgresChangesFilter
- Option 6RealtimePostgresChangesFilter
- Option 7RealtimePostgresChangesFilter
- Option 8RealtimePostgresChangesFilter
- Option 9RealtimePostgresChangesFilter
- Option 10object
- Option 11object
- Option 12object
- Option 13object
- Option 14object
callbackfunction

1
const channel = supabase.channel("room1")
2
3
channel.on("broadcast", { event: "cursor-pos" }, (payload) => {
4
  console.log("Cursor position received!", payload);
5
}).subscribe((status) => {
6
  if (status === "SUBSCRIBED") {
7
    channel.send({
8
      type: "broadcast",
9
      event: "cursor-pos",
10
      payload: { x: Math.random(), y: Math.random() },
11
    });
12
  }
13
});

onHeartbeat

onHeartbeat(callback)

Sets a callback that receives lifecycle events for internal heartbeat messages. Useful for instrumenting connection health (e.g. sent/ok/timeout/disconnected).

Parameters

callbackHeartbeatCallback

Return Type

void

presenceState

presenceState()

Returns the current presence state for this channel.

The shape is a map keyed by presence key (for example a user id) where each entry contains the tracked metadata for that user.

Return Type

{ [key: string]: Array<Presence> }

push

push(data)

Push out a message if the socket is connected.

If the socket is not connected, the message gets enqueued within a local buffer, and sent out when a connection is next established.

Parameters

dataRealtimeMessage

Return Type

void

removeAllChannels

removeAllChannels()

Unsubscribes, removes and tears down all channels

Return Type

Promise<Array<One of the following options>>

removeChannel

removeChannel(channel)

Unsubscribes, removes and tears down a single channel

Parameters

channelRealtimeChannel
A RealtimeChannel instance

Return Type

Promise<One of the following options>

Option 1"ok"
Option 2"timed out"
Option 3"error"
Option 4

send

send(args, opts)

Sends a message into the channel.

When using REST you don't need to subscribe to the channel
REST calls are only available from 2.37.0 onwards
If you create a channel only to send a REST broadcast, remove it from the client when the send completes

Parameters

argsobject
Arguments to send to channel
opts{ [key: string]: any }
Options to be used during the send process

Return Type

Promise<One of the following options>

Option 1"ok"
Option 2"timed out"
Option 3"error"
Option 4

1
const channel = supabase.channel('room1')
2
3
channel.subscribe((status) => {
4
  if (status === 'SUBSCRIBED') {
5
    channel.send({
6
      type: 'broadcast',
7
      event: 'cursor-pos',
8
      payload: { x: Math.random(), y: Math.random() },
9
    })
10
  }
11
})

sendHeartbeat

sendHeartbeat()

Sends a heartbeat message if the socket is connected.

Return Type

Promise<void>

setAuth

setAuth(token)

Sets the JWT access token used for channel subscription authorization and Realtime RLS.

If param is null it will use the accessToken callback function or the token set on the client.

On callback used, it will set the value of the token internal to the client.

When a token is explicitly provided, it will be preserved across channel operations (including removeChannel and resubscribe). The accessToken callback will not be invoked until setAuth() is called without arguments.

Parameters

tokenOne of the following options
A JWT string to override the token set on the client.
- Option 1null
- Option 2string

Return Type

Promise<void>

1
Setting the authorization header
2
// Use a manual token (preserved across resubscribes, ignores accessToken callback)
3
client.realtime.setAuth('my-custom-jwt')
4
5
// Switch back to using the accessToken callback
6
client.realtime.setAuth()

subscribe(callback?, timeout)

Subscribe registers your client with the server.

The optional callback receives a status and, on failure, an err argument. Log the full err so its cause, name, and any structured fields aren't hidden behind err.message.

Parameters

callback
Optional
function
timeoutnumber

1
supabase.channel('room1').subscribe((status, err) => {
2
  if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
3
    // Log the full error: its `cause` often holds the underlying reason.
4
    console.error(status, err)
5
  }
6
})

teardown

teardown()

Destroys and stops related timers.

Return Type

void

track

track(payload, opts)

Sends the supplied payload to the presence tracker so other subscribers can see that this client is online. Use untrack to stop broadcasting presence for the same key.

Parameters

payload{ [key: string]: any }
opts{ [key: string]: any }

Return Type

Promise<One of the following options>

Option 1"ok"
Option 2"timed out"
Option 3"error"
Option 4

unsubscribe

unsubscribe(timeout)

Leaves the channel.

Unsubscribes from server events, and instructs channel to terminate on server. Triggers onClose() hooks.

To receive leave acknowledgements, use the a receive hook to bind to the server ack, ie: channel.unsubscribe().receive("ok", () => alert("left!") )

Parameters

timeoutnumber

Return Type

Promise<One of the following options>

Option 1"ok"
Option 2"timed out"
Option 3"error"
Option 4

untrack

untrack(opts)

Removes the current presence state for this client.

Parameters

opts{ [key: string]: any }

Return Type

Promise<One of the following options>

Option 1"ok"
Option 2"timed out"
Option 3"error"
Option 4

updateJoinPayload

updateJoinPayload(payload)

Updates the payload that will be sent the next time the channel joins (reconnects). Useful for rotating access tokens or updating config without re-creating the channel.

Parameters

payloadRecord<string, any>

Return Type

void

Analytics Buckets

This section contains methods for working with Analytics Buckets.

createBucket

createBucket(name)

Creates a new analytics bucket using Iceberg tables Analytics buckets are optimized for analytical queries and data processing

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Creates a new analytics bucket using Iceberg tables
Analytics buckets are optimized for analytical queries and data processing

Parameters

namestring
A unique name for the bucket you are creating

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .analytics
4
  .createBucket('analytics-data')

deleteBucket

deleteBucket(bucketName)

Deletes an existing analytics bucket A bucket can't be deleted with existing objects inside it You must first empty the bucket before deletion

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Deletes an analytics bucket

Parameters

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .analytics
4
  .deleteBucket('analytics-data')

from

from(bucketName)

Get an Iceberg REST Catalog client configured for a specific analytics bucket Use this to perform advanced table and namespace operations within the bucket The returned client provides full access to the Apache Iceberg REST Catalog API with the Supabase { data, error } pattern for consistent error handling on all operations.

Public alpha: This API is part of a public alpha release and may not be available to your account type.

This method provides a bridge between Supabase's bucket management and the standard Apache Iceberg REST Catalog API. The bucket name maps to the Iceberg warehouse parameter. All authentication and configuration is handled automatically using your Supabase credentials.

Error Handling: Invalid bucket names throw immediately. All catalog operations return { data, error } where errors are IcebergError instances from iceberg-js. Use helper methods like error.isNotFound() or check error.status for specific error handling. Use .throwOnError() on the analytics client if you prefer exceptions for catalog operations.

Cleanup Operations: When using dropTable, the purge: true option permanently deletes all table data. Without it, the table is marked as deleted but data remains.

Library Dependency: The returned catalog wraps IcebergRestCatalog from iceberg-js. For complete API documentation and advanced usage, refer to the iceberg-js documentation.

Parameters

bucketNamestring
The name of the analytics bucket (warehouse) to connect to

1
// First, create an analytics bucket
2
const { data: bucket, error: bucketError } = await supabase
3
  .storage
4
  .analytics
5
  .createBucket('analytics-data')
6
7
// Get the Iceberg catalog for that bucket
8
const catalog = supabase.storage.analytics.from('analytics-data')
9
10
// Create a namespace
11
const { error: nsError } = await catalog.createNamespace({ namespace: ['default'] })
12
13
// Create a table with schema
14
const { data: tableMetadata, error: tableError } = await catalog.createTable(
15
  { namespace: ['default'] },
16
  {
17
    name: 'events',
18
    schema: {
19
      type: 'struct',
20
      fields: [
21
        { id: 1, name: 'id', type: 'long', required: true },
22
        { id: 2, name: 'timestamp', type: 'timestamp', required: true },
23
        { id: 3, name: 'user_id', type: 'string', required: false }
24
      ],
25
      'schema-id': 0,
26
      'identifier-field-ids': [1]
27
    },
28
    'partition-spec': {
29
      'spec-id': 0,
30
      fields: []
31
    },
32
    'write-order': {
33
      'order-id': 0,
34
      fields: []
35
    },
36
    properties: {
37
      'write.format.default': 'parquet'
38
    }
39
  }
40
)

listBuckets

listBuckets(options?)

Retrieves the details of all Analytics Storage buckets within an existing project Only returns buckets of type 'ANALYTICS'

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Retrieves the details of all Analytics Storage buckets within an existing project
Only returns buckets of type 'ANALYTICS'

Parameters

options
Optional
object
Query parameters for listing buckets

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .analytics
4
  .listBuckets({
5
    limit: 10,
6
    offset: 0,
7
    sortColumn: 'created_at',
8
    sortOrder: 'desc'
9
  })

File Buckets

This section contains methods for working with File Buckets.

copy

copy(fromPath, toPath, options?)

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

fromPathstring
The original file path, including the current file name. For example folder/image.png.
toPathstring
The new file path, including the new file name. For example folder/image-copy.png.
options
Optional
DestinationOptions
The destination options.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

createBucket

createBucket(id, options)

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

idstring
A unique identifier for the bucket you are creating.
optionsobject

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .createBucket('avatars', {
4
    public: false,
5
    allowedMimeTypes: ['image/png'],
6
    fileSizeLimit: 1024
7
  })

createSignedUploadUrl

createSignedUploadUrl(path, options?)

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

pathstring
The file path, including the current file name. For example folder/image.png.
options
Optional
object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

createSignedUrl

createSignedUrl(path, expiresIn, options?)

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

pathstring
The file path, including the current file name. For example folder/image.png.
expiresInnumber
The number of seconds until the signed URL expires. For example, 60 for a URL which is valid for one minute.
options
Optional
object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

createSignedUrls

createSignedUrls(paths, expiresIn, options?)

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

pathsArray<string>
The file paths to be downloaded, including the current file names. For example ['folder/image.png', 'folder2/image2.png'].
expiresInnumber
The number of seconds until the signed URLs expire. For example, 60 for URLs which are valid for one minute.
options
Optional
object

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

deleteBucket

deleteBucket(id)

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

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

download

download(path, options?, parameters?)

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

pathstring
The full path and file name of the file to be downloaded. For example folder/image.png.
options
Optional
Options
parameters
Optional
FetchParameters
Additional fetch parameters like signal for cancellation. Supports standard fetch options including cache control.

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

emptyBucket

emptyBucket(id)

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

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

exists

exists(path)

Checks the existence of a file.

Parameters

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .exists('folder/avatar1.png')

from

from(id)

Perform file operation in a bucket.

Parameters

idstring
The bucket id to operate on.

1
const avatars = supabase.storage.from('avatars')

getBucket

getBucket(id)

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

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

getPublicUrl

getPublicUrl(path, options?)

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

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

Return Type

object

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

info

info(path)

Retrieves the details of an existing file.

Returns detailed file metadata including size, content type, and timestamps. Note: The API returns last_modified field, not updated_at.

Parameters

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .info('folder/avatar1.png')
5
6
if (data) {
7
  console.log('Last modified:', data.lastModified)
8
  console.log('Size:', data.size)
9
}

list

list(path?, options?, parameters?)

Lists all the files and folders within a path of the bucket.

Important: For folder entries, fields like id, updated_at, created_at, last_accessed_at, and metadata will be null. Only files have these fields populated. Additionally, deprecated fields like bucket_id, owner, and buckets are NOT returned by this method.

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
Search options including limit (defaults to 100), offset, sortBy, and search
parameters
Optional
FetchParameters
Optional fetch parameters including signal for cancellation

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .list('folder', {
5
    limit: 100,
6
    offset: 0,
7
    sortBy: { column: 'name', order: 'asc' },
8
  })
9
10
// Handle files vs folders
11
data?.forEach(item => {
12
  if (item.id !== null) {
13
    // It's a file
14
    console.log('File:', item.name, 'Size:', item.metadata?.size)
15
  } else {
16
    // It's a folder
17
    console.log('Folder:', item.name)
18
  }
19
})

listBuckets

listBuckets(options?)

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

Parameters

options
Optional
ListBucketOptions
Query parameters for listing buckets

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

listV2

listV2(options?, parameters?)

Lists all the files and folders within a bucket using the V2 API with pagination support.

Important: Folder entries in the folders array only contain name and optionally key — they have no id, timestamps, or metadata fields. Full file metadata is only available on entries in the objects array.

this method signature might change in the future

Parameters

options
Optional
SearchV2Options
Search options including prefix, cursor for pagination, limit, with_delimiter
parameters
Optional
FetchParameters
Optional fetch parameters including signal for cancellation

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .listV2({
5
    prefix: 'folder/',
6
    limit: 100,
7
  })
8
9
// Handle pagination
10
if (data?.hasNext) {
11
  const nextPage = await supabase
12
    .storage
13
    .from('avatars')
14
    .listV2({
15
      prefix: 'folder/',
16
      cursor: data.nextCursor,
17
    })
18
}
19
20
// Handle files vs folders
21
data?.objects.forEach(file => {
22
  if (file.id !== null) {
23
    console.log('File:', file.name, 'Size:', file.metadata?.size)
24
  }
25
})
26
data?.folders.forEach(folder => {
27
  console.log('Folder:', folder.name)
28
})

move

move(fromPath, toPath, options?)

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

fromPathstring
The original file path, including the current file name. For example folder/image.png.
toPathstring
The new file path, including the new file name. For example folder/image-new.png.
options
Optional
DestinationOptions
The destination options.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

remove

remove(paths)

Deletes files within the same bucket

Returns an array of FileObject entries for the deleted files. Note that deprecated fields like bucket_id may or may not be present in the response - do not rely on them.

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

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

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

update

update(path, fileBody, fileOptions?)

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
update() always replaces the file at the given path regardless of the upsert option.
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

pathstring
The relative file path. Should be of the format folder/subfolder/filename.png. The bucket must already exist before attempting to update.
fileBodyOne of the following options
The body of the file to be stored in the bucket.
- Option 1string
- Option 2ArrayBuffer
- Option 3ReadableStream
- Option 4Blob
- Option 5File
- Option 6FormData
- Option 7@types/node.__global.NodeJS.ReadableStream
- Option 8URLSearchParams
- Option 9ArrayBufferView
- Option 10@types/node.__global.Buffer
fileOptions
Optional
FileOptions
Optional file upload options including cacheControl, contentType, and metadata. Note: The upsert option has no effect here. update() always replaces the file at the given path, so the x-upsert header is not sent. To control upsert behavior, use upload() instead.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const avatarFile = event.target.files[0]
2
const { data, error } = await supabase
3
  .storage
4
  .from('avatars')
5
  .update('public/avatar1.png', avatarFile, {
6
    cacheControl: '3600'
7
  })

updateBucket

updateBucket(id, options)

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

idstring
A unique identifier for the bucket you are updating.
optionsobject

Return Type

Promise<One of the following options>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .updateBucket('avatars', {
4
    public: false,
5
    allowedMimeTypes: ['image/png'],
6
    fileSizeLimit: 1024
7
  })

upload

upload(path, fileBody, fileOptions?)

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

pathstring
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.
fileBodyFileBody
The body of the file to be stored in the bucket.
fileOptions
Optional
FileOptions
Optional file upload options including cacheControl, contentType, upsert, and metadata.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

uploadToSignedUrl

uploadToSignedUrl(path, token, fileBody, fileOptions?)

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

pathstring
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.
tokenstring
The token generated from createSignedUploadUrl
fileBodyFileBody
The body of the file to be stored in the bucket.
fileOptions
Optional
FileOptions
HTTP headers (cacheControl, contentType, etc.). Note: The upsert option has no effect here. To enable upsert behavior, pass { upsert: true } when calling createSignedUploadUrl() instead.

Return Type

Promise<One of the following options>

Option 1object
Option 2object

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

Vector Buckets

This section contains methods for working with Vector Buckets.

createBucket

createBucket(vectorBucketName)

Creates a new vector bucket Vector buckets are containers for vector indexes and their data

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

vectorBucketNamestring
Unique name for the vector bucket

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .createBucket('embeddings-prod')

createIndex

createIndex(options)

Creates a new vector index in this bucket Convenience method that automatically includes the bucket name

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Index configuration (vectorBucketName is automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
await bucket.createIndex({
3
  indexName: 'documents-openai',
4
  dataType: 'float32',
5
  dimension: 1536,
6
  distanceMetric: 'cosine',
7
  metadataConfiguration: {
8
    nonFilterableMetadataKeys: ['raw_text']
9
  }
10
})

deleteBucket

deleteBucket(vectorBucketName)

Deletes a vector bucket (bucket must be empty) All indexes must be deleted before deleting the bucket

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

vectorBucketNamestring
Name of the vector bucket to delete

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .deleteBucket('embeddings-old')

deleteIndex

deleteIndex(indexName)

Deletes an index from this bucket Convenience method that automatically includes the bucket name

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

indexNamestring
Name of the index to delete

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
await bucket.deleteIndex('old-index')

deleteVectors

deleteVectors(options)

Deletes vectors by keys from this index Convenience method that automatically includes bucket and index names

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Deletion options (bucket and index names automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
await index.deleteVectors({
3
  keys: ['doc-1', 'doc-2', 'doc-3']
4
})

from

from(vectorBucketName)

Access operations for a specific vector bucket Returns a scoped client for index and vector operations within the bucket

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

vectorBucketNamestring
Name of the vector bucket

1
const bucket = supabase.storage.vectors.from('embeddings-prod')

getBucket

getBucket(vectorBucketName)

Retrieves metadata for a specific vector bucket

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

vectorBucketNamestring
Name of the vector bucket

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .getBucket('embeddings-prod')
5
6
console.log('Bucket created:', data?.vectorBucket.creationTime)

getIndex

getIndex(indexName)

Retrieves metadata for a specific index in this bucket Convenience method that automatically includes the bucket name

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

indexNamestring
Name of the index to retrieve

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
const { data } = await bucket.getIndex('documents-openai')
3
console.log('Dimension:', data?.index.dimension)

getVectors

getVectors(options)

Retrieves vectors by keys from this index Convenience method that automatically includes bucket and index names

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Vector retrieval options (bucket and index names automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
const { data } = await index.getVectors({
3
  keys: ['doc-1', 'doc-2'],
4
  returnMetadata: true
5
})

index

VectorBucketScope(indexName)

Access operations for a specific index within this bucket Returns a scoped client for vector data operations

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

indexNamestring
Name of the index

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
3
// Insert vectors
4
await index.putVectors({
5
  vectors: [
6
    { key: 'doc-1', data: { float32: [...] }, metadata: { title: 'Intro' } }
7
  ]
8
})
9
10
// Query similar vectors
11
const { data } = await index.queryVectors({
12
  queryVector: { float32: [...] },
13
  topK: 5
14
})

listBuckets

listBuckets(options)

Lists all vector buckets with optional filtering and pagination

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsListVectorBucketsOptions
Optional filters (prefix, maxResults, nextToken)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .listBuckets({ prefix: 'embeddings-' })
5
6
data?.vectorBuckets.forEach(bucket => {
7
  console.log(bucket.vectorBucketName)
8
})

listIndexes

listIndexes(options)

Lists indexes in this bucket Convenience method that automatically includes the bucket name

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Listing options (vectorBucketName is automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
const { data } = await bucket.listIndexes({ prefix: 'documents-' })

listVectors

listVectors(options)

Lists vectors in this index with pagination Convenience method that automatically includes bucket and index names

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Listing options (bucket and index names automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
const { data } = await index.listVectors({
3
  maxResults: 500,
4
  returnMetadata: true
5
})

putVectors

putVectors(options)

Inserts or updates vectors in this index Convenience method that automatically includes bucket and index names

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Vector insertion options (bucket and index names automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
await index.putVectors({
3
  vectors: [
4
    {
5
      key: 'doc-1',
6
      data: { float32: [0.1, 0.2, ...] },
7
      metadata: { title: 'Introduction', page: 1 }
8
    }
9
  ]
10
})

queryVectors

queryVectors(options)

Queries for similar vectors in this index Convenience method that automatically includes bucket and index names

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

optionsOmit
Query options (bucket and index names automatically set)

Return Type

Promise<One of the following options>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
const { data } = await index.queryVectors({
3
  queryVector: { float32: [0.1, 0.2, ...] },
4
  topK: 5,
5
  filter: { category: 'technical' },
6
  returnDistance: true,
7
  returnMetadata: true
8
})