Kotlin Reference v2.0

Kotlin Client Library

@supabase-community/supabase-kt

This reference documents every object and method available in Supabase's Kotlin Multiplatform library, supabase-kt. You can use supabase-kt 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 see supported Kotlin targets, check the corresponding module README on GitHub.

To migrate from version 1.4.X to 2.0.0, see the migration guide

The Kotlin client library is created and maintained by the Supabase community, and is not an official library. Please be tolerant of areas where the library is still being developed, and — as with all the libraries — feel free to contribute wherever you find issues.

Huge thanks to official maintainer, jan-tennert.

Installing

Add one or more modules to your project

latest stable supabase-kt versionlatest supabase-kt version

Add dependency to your build file:


_10
implementation("io.github.jan-tennert.supabase:[module]:VERSION")

The available modules are:

When using multiple modules, you can also use the BOM dependency to ensure that all modules use the same version:


_10
implementation(platform("io.github.jan-tennert.supabase:bom:VERSION"))
_10
implementation("io.github.jan-tennert.supabase:postgrest-kt")
_10
implementation("io.github.jan-tennert.supabase:realtime-kt")

Add Ktor Client Engine to each of your Kotlin targets (required)

You can find a list of engines here


_10
implementation("io.ktor:ktor-client-[engine]:KTOR_VERSION")

Multiplatform example:


_23
val commonMain by getting {
_23
dependencies {
_23
//supabase modules
_23
}
_23
}
_23
val jvmMain by getting {
_23
dependencies {
_23
implementation("io.ktor:ktor-client-cio:KTOR_VERSION")
_23
}
_23
}
_23
val androidMain by getting {
_23
dependsOn(jvmMain)
_23
}
_23
val jsMain by getting {
_23
dependencies {
_23
implementation("io.ktor:ktor-client-js:KTOR_VERSION")
_23
}
_23
}
_23
val iosMain by getting {
_23
dependencies {
_23
implementation("io.ktor:ktor-client-darwin:KTOR_VERSION")
_23
}
_23
}

Serialization

supabase-kt provides several different ways to encode and decode your custom objects. By default, KotlinX Serialization is used.

Use KotlinX Serialization.


_10
plugins {
_10
kotlin("plugin.serialization") version "KOTLIN_VERSION"
_10
}


_10
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
_10
//Already the default serializer, but you can provide a custom Json instance (optional):
_10
defaultSerializer = KotlinXSerializer(Json {
_10
//apply your custom config
_10
})
_10
}

Use Moshi.


_10
implementation("io.github.jan-tennert.supabase:serializer-moshi:VERSION")


_10
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
_10
defaultSerializer = MoshiSerializer()
_10
}

Use Jackson.


_10
implementation("io.github.jan-tennert.supabase:serializer-jackson:VERSION")


_10
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
_10
defaultSerializer = JacksonSerializer()
_10
}

Use custom serializer.


_11
class CustomSerializer: SupabaseSerializer {
_11
_11
override fun <T : Any> encode(type: KType, value: T): String {
_11
//encode value to string
_11
}
_11
_11
override fun <T : Any> decode(type: KType, value: String): T {
_11
//decode value
_11
}
_11
_11
}


_10
val supabase = createSupabaseClient(supabaseUrl, supabaseKey) {
_10
defaultSerializer = CustomSerializer()
_10
}

Initializing

Create Supabase Client

Independently of which Supabase module you are using, you will need to initialize the main client first and install the module.

To create a new client, you can use the createSupabaseClient function.

When installing a module, you can pass a block to configure it.

OAuth and OTP link verification

supabase-kt provides several platform implementations for OAuth and OTP link verification.
On Desktop platforms (JVM, MacOS*, Linux), it uses a HTTP Callback Server to receive the session data from a successful OAuth login. The success page can be customized via AuthConfig#httpCallbackConfig * If no deeplinks are being used.

Note: OTP link verification such as sign ups are not supported on JVM. You may have to send a verification token rather than a url in your email. To send the token, rather than a redirect url, change {{ .ConfirmationURL }} in your sign up email to {{ .Token }}

On Android, iOS & MacOS, OAuth and OTP verification use deeplinks. Refer to the guide below on how to setup deeplinks. Alternatively you can use Native Google Auth. Refer to the Supabase Auth documentation to learn more. On JS, it uses the website origin as the callback url. Session importing gets handled automatically. Windows, tvOS, watchOS & Linux currently have no default implementation. Feel free to create a PR.

You always make your own implementation and use auth.parseSessionFromFragment(fragment) or auth.parseSessionFromUrl(url) to let supabase-kt handle the parsing after receiving a callback. Then you can simply use auth.importSession(session).

Configure deeplink callbacks for Authentication

Deeplinks are supported on Android, iOS and MacOS.

  1. Set up a deeplink
    On Android, set up a deeplink in your Android manifest.
    On iOS and MacOS, set up a url scheme.
  2. Add your deeplink to the redirect URLs
    Pattern: scheme://host
  3. Configure the Auth plugin Set the host and scheme in the Auth config: 
    install(Auth) {
   host = "deeplink host" // this can be anything, eg. your package name or app/company url (not your Supabase url)
   scheme = "deeplink scheme"

   // On Android only, you can set OAuth and SSO logins to open in a custom tab, rather than an external browser:
   defaultExternalAuthAction = ExternalAuthAction.CustomTabs() //defaults to ExternalAuthAction.ExternalBrowser
}
  4. Call platform specific function on startup
    On Android: supabase.handleDeeplinks(intent)
    If you don't want a separate activity, just call this function at the top of your onCreate function in your MainActivity.
    On iOS/MacOS: supabase.handleDeeplinks(url)

Then you can log in using OAuth:

supabase.auth.signInWith(Google)

Or open OTP links directly in your app.

PKCE Authentication flow

supabase-kt supports the PKCE authentication flow. To use it, change the flowType in the Auth configuration:

install(Auth) {
  flowType = FlowType.PKCE
}

That's it! If you already implemented deeplinks to handle OTPs and OAuth you don't have to change anything!

Parameters
    supabaseUrl
    REQUIRED
    String

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

    supabaseKey
    REQUIRED
    String

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

    builder
    Optional
    SupabaseClientBuilder.() -> Unit

    Apply additional configuration and install plugins.


val supabase = createSupabaseClient(
    supabaseUrl = "https://xyzcompany.supabase.co",
    supabaseKey = "public-anon-key"
) {
    install(Auth)
    install(Postgrest)
    //install other modules
}

Fetch data

Perform a SELECT query on the table or view.

  • When calling a decode method, you have to provide a serializable class as the type parameter.
  • You can provide a Columns object to select specific columns.
  • You can provide a filter block to filter the results
Parameters
    columns
    Optional
    Columns

    The columns to retrieve, defaults to Columns.ALL. You can also use Columns.list, Columns.type or Columns.raw to specify the columns.

    head
    Optional
    Boolean

    If true, select will delete the selected data.

    request
    Optional
    PostgrestRequestBuilder.() -> Unit

    Additional configuration & filtering for the request.


val city = supabase.from("cities").select().decodeSingle<City>()

Insert data

  • When calling an insert method, you have to provide a serializable value.
  • By default, every time you run insert(), the client library will make a select to return the full record. This is convenient, but it can also cause problems if your policies are not configured to allow the select operation.
Parameters
    value
    REQUIRED
    T or List<T>

    The value(s) you want to insert. T can be any serializable type.

    request
    Optional
    PostgrestRequestBuilder.() -> Unit

    Additional configuration & filtering for the request.


val city = City(name = "The Shire", countryId = 554)
supabase.from("cities").insert(city)

Update data

  • update() should always be combined with a filter block to avoid updating all records.
  • When calling insert or update, you have to provide a serializable value in the function parameter.
Parameters
    value
    REQUIRED
    T or PostgrestUpdate.() -> Unit = {}

    The new value, can be either a serializable value or PostgrestUpdate DSL where you can set new values per column.

    request
    Optional
    PostgrestRequestBuilder.() -> Unit

    Additional configuration & filtering for the request.


supabase.from("countries").update(
    {
       Country::name setTo "Australia"
       //or
       set("name", "Australia")
    }
) {
    filter {
        Country::id eq 1
        //or
        eq("id", 1)
    }
}

Upsert data

  • Primary keys should be included in the data payload in order for an update to work correctly.
  • Primary keys must be natural, not surrogate. There are however, workarounds for surrogate primary keys.
  • If you need to insert new data and update existing data at the same time, use Postgres triggers.
  • When calling insert or update, you have to provide a serializable value in the function parameter.
Parameters
    value
    REQUIRED
    T or List<T>

    The value(s) you want to insert. T can be any serializable type.

    onConflict
    Optional
    String?

    Comma-separated UNIQUE column(s) to specify how duplicate rows are determined. Two rows are duplicates if all the onConflict columns are equal.

    defaultToNull
    Optional
    Boolean

    Make missing fields default to null. Otherwise, use the default value for the column. This only applies when inserting new rows, not when merging with existing rows under

    ignoreDuplicates
    Optional
    Boolean

    If true, duplicate rows are ignored. If false, duplicate rows are merged with existing rows.

    request
    Optional
    PostgrestRequestBuilder.() -> Unit

    Additional configuration & filtering for the request.


val toUpsert = Message(id = 3, message = "foo", username = "supabot")
supabase.from("messages").upsert(toUpsert)

Delete data

  • delete() should always be combined with a filter block to target the item(s) you wish to delete.
  • If you use delete() with filters and you have RLS enabled, only rows visible through SELECT policies are deleted. Note that by default no rows are visible, so you need at least one SELECT/ALL policy that makes the rows visible.
Parameters
    request
    Optional
    PostgrestRequestBuilder.() -> Unit

    Additional configuration & filtering for the request.


supabase.from("cities").delete {
    filter {
        City::id eq 666
        //or
        eq("id", 666)
    }
}

Call a Postgres function

You can call stored procedures as a "Remote Procedure Call".

That's a fancy way of saying that you can put some logic into your database then call it from anywhere. It's especially useful when the logic rarely changes - like password resets and updates.

  • When calling rpc with parameters, you have to provide a serializable value in the function parameter.
Parameters
    function
    REQUIRED
    String

    The name of the function

    parameters
    Optional
    T

    Parameters to pass to the function. T can be any serializable type.

    method
    Optional
    RpcMethod

    The HTTP method to use. Defaults to RpcMethod.POST

    request
    Optional
    PostgrestRequestBuilder.() -> Unit

    Additional configuration & filtering for the request.


supabase.postgrest.rpc("hello_world")

Using filters

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

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

You can use two different types for applying filters:

eq("country_id", 1)

And using a class property:

City::countryId eq 1

As you can see on the property syntax: the name of the countryId gets converted to country_id.

By default, this is done by converting camel case to snake case, but you can customize this by changing the propertyConversionMethod in the Postgrest Config

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


supabase.from("cities").select(columns = Columns.list("name", "country_id")) {
    filter {
        City::name eq "The Shire"
        //or
        eq("name", "The Shire")
    }
}

Column is equal to a value

Finds all rows whose value on the stated column exactly matches the specified value.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name", "country_id")) {
    filter {
        City::name eq "The Shire"
        //or
        eq("name", "The Shire")
    }
}

Column is not equal to a value

Finds all rows whose value on the stated column doesn't match the specified value.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name", "country_id")) {
    filter {
        City::name neq "The Shire"
        //or
        neq("name", "The Shire")
    }
}

Column is greater than a value

Finds all rows whose value on the stated column is greater than the specified value.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::countryId gt 300
       //or
       gt("country_id", 300)
    }
}

Column is greater than or equal to a value

Finds all rows whose value on the stated column is greater than or equal to the specified value.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::countryId gte 300
       //or
       gte("country_id", 300)
    }
}

Column is less than a value

Finds all rows whose value on the stated column is less than the specified value.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::countryId lt 300
       //or
       lt("country_id", 300)
    }
}

Column is less than or equal to a value

Finds all rows whose value on the stated column is less than or equal to the specified value.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::countryId lte 300
       //or
       lte("country_id", 300)
    }
}

Column matches a pattern

Finds all rows whose value in the stated column matches the supplied pattern (case sensitive).

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    pattern
    REQUIRED
    String

    The pattern to match with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::name like "%la%"
       //or
       like("name", "%la%")
    }
}

Column matches a case-insensitive pattern

Finds all rows whose value in the stated column matches the supplied pattern (case insensitive).

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    pattern
    REQUIRED
    String

    The pattern to match with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::name ilike "%la%"
       //or
       ilike("name", "%la%")
    }
}

Column is a value

A check for exact equality (null, true, false), finds all rows whose value on the stated column exactly match the specified value.

is_ and in_ filter methods are suffixed with _ to avoid collisions with reserved keywords.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    value
    REQUIRED
    Boolean?

    The value to filter with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::name isExact null
       //or
       exact("name", null)
    }
}

Column is in an array

Finds all rows whose value on the stated column is found on the specified values.

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    List<Any>

    The values to filter with.


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::name isIn listOf("Rio de Janeiro", "San Francisco")
       //or
       isIn("name", listOf("Rio de Janeiro", "San Francisco"))
    }
}

Column contains every element in a value

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

Parameters
    column
    REQUIRED
    String

    The jsonb, array, or range column to filter on

    value
    REQUIRED
    List<Any>

    The jsonb, array, or range value to filter with


supabase.from("cities").select(columns = Columns.list("name")) {
    filter {
       City::mainExports contains listOf("oil")
       //or
       contains("main_exports", listOf("oil"))
    }
}

Greater than a range

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    Pair<Any, Any>

    The values to filter with.


  supabase.from("reservations").select {
      filter {
         Reservation::during rangeGt ("2000-01-02 08:30" to "2000-01-02 09:30")
         //or
         rangeGt("during", "2000-01-02 08:30" to "2000-01-02 09:30")
      }
  }

Greater than or equal to a range

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    Pair<Any, Any>

    The values to filter with.


  supabase.from("reservations").select {
      filter {
         Reservation::during rangeGte ("2000-01-02 08:30" to "2000-01-02 09:30")
         //or
         rangeGte("during", "2000-01-02 08:30" to "2000-01-02 09:30")
      }
  }

Less than a range

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    Pair<Any, Any>

    The values to filter with.


  supabase.from("reservations").select {
      filter {
         Reservation::during rangeLt ("2000-01-02 08:30" to "2000-01-02 09:30")
         //or
         rangeLt("during", "2000-01-02 08:30" to "2000-01-02 09:30")
      }
  }

Less than or equal to a range

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    Pair<Any, Any>

    The values to filter with.


  supabase.from("reservations").select {
      filter {
         Reservation::during rangeLte ("2000-01-02 08:30" to "2000-01-02 09:30")
         //or
         rangeLte("during", "2000-01-02 08:30" to "2000-01-02 09:30")
      }
  }

Mutually exclusive to a range

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    Pair<Any, Any>

    The values to filter with.


  supabase.from("reservations").select {
      filter {
         Reservation::during adjacent ("2000-01-02 08:30" to "2000-01-02 09:30")
         //or
         adjacent("during", "2000-01-02 08:30" to "2000-01-02 09:30")
      }
  }

With a common element

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    values
    REQUIRED
    List<Any>

    The values to filter with.


supabase.from("issues").select(columns = Columns.list("title")) {
    filter {
       Issue::tags overlaps listOf("is:closed", "severity:high")
       //or
       overlaps("tags", listOf("is:closed", "severity:high"))
    }
}

Match a string

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

For more information, see Postgres full text search.

Parameters
    column
    REQUIRED
    String

    The text or tsvector column to filter on

    query
    REQUIRED
    String

    The query text to match with

    textSearchType
    Optional
    TextSearchType

    The type of text search to use. Defaults to TextSearchType.NONE.

    config
    Optional
    String

    The text search configuration to use.


supabase.from("quotes").select(columns = Columns.list("catchphrase")) {
    filter {
       textSearch(column = "catchphrase", query = "'fat' & 'cat'", config = "english", type = TextSearchType.YOUR_TYPE)
    }
}

Don't match the filter

Finds all rows that don't satisfy the filter.

  • .filterNot() expects you to use the raw PostgREST syntax for the filter names and values.
Parameters
    column
    REQUIRED
    String

    The column to filter on.

    operator
    REQUIRED
    FilterOperator

    The operator to use for the filter.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("countries").select {
    filter {
        filterNot("name", FilterOperation.IS, "")
    }
}

Match at least one filter

Finds all rows satisfying at least one of the filters.

Parameters
    negate
    Optional
    Boolean

    If true, negate the entire block.

    block
    REQUIRED
    PostgrestFilterBuilder.() -> Unit

    The block to apply the or filter to.


supabase.from("countries").select(columns = Columns.list("name")) {
    filter {
        or {
            Country::id eq 2
            Country::name eq "Algeria"
            //or
            eq("id", 2)
            eq("name", "Algeria")
        }
    }
}

Match the filter

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

Parameters
    column
    REQUIRED
    String

    The column to filter on.

    operator
    REQUIRED
    FilterOperator

    The operator to use for the filter.

    value
    REQUIRED
    Any

    The value to filter with.


supabase.from("countries").select {
    filter {
       filter(column = "name", operator = FilterOperator.IN, value = "('Algeria', 'Japan')")
    } 
}

Using modifiers

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

Modifiers are be specified next to the filter block. Some modifiers only apply for queries that return rows (e.g., select() or rpc() on a function that returns a table response).

Return data after inserting

Parameters
    columns
    Optional
    Columns

    The columns to select.


val toUpsert = Country(id = 2, name = "Algeria")
val count = supabase.from("countries").upsert(toUpsert) {
    select()
}.decodeSingle<Country>()

Order the results

Order the query result by column.

Parameters
    column
    REQUIRED
    String

    The column to order by.

    order
    REQUIRED
    Order

    The order to use.

    nullsFirst
    Optional
    Boolean

    Whether to order nulls first.

    referencedTable
    Optional
    String

    The foreign table to order by.


supabase.from("countries").select(columns = Columns.list("id", "name")) {
   order(column = "id", order = Order.ASCENDING)
}

Limit the number of rows returned

Limit the query result by count.

Parameters
    count
    REQUIRED
    Long

    The number of rows to limit the result to.

    referencedTable
    Optional
    String

    The foreign table to limit by.


supabase.from("countries").select {
    limit(count = 1)
}

Limit the query to a range

Limit the query result by from and to inclusively.

Parameters
    from
    REQUIRED
    Long

    The start of the range.

    to
    REQUIRED
    Long

    The end of the range.

    referencedTable
    Optional
    String

    The foreign table to limit by.


supabase.from("countries").select {
    range(1L..5L)
}

Retrieve one row of data


val result = supabase.from("countries").select(Columns.list("name")) {
    limit(1)
    single()
}

Retrieve as a CSV


val (csvData, _) = supabase.from("countries").select {
    csv()
}

Using explain

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

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

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

Parameters
    analyze
    Optional
    Boolean

    If true, the query will be executed and the actual run time will be returned

    verbose
    Optional
    Boolean

    If true, the query identifier will be returned and data will include the output columns of the query

    settings
    Optional
    Boolean

    If true, include information on configuration parameters that affect query planning

    buffers
    Optional
    Boolean

    If true, include information on buffer usage

    wal
    Optional
    Boolean

    If true, include information on WAL record generation

    format
    Optional
    String

    The format of the output, can be "text" (default) or "json"


val result = supabase.from("countries").select {
    explain()
}

Overview

  • The auth methods can be accessed via the Supabase Auth client.

val supabase = createSupabaseClient(supabaseURL = "https://xyzcompany.supabase.co'", supabaseKey = "public-anon-key") { ... }
val auth = supabase.auth

Error codes

Supabase Auth can throw or return various errors when using the API. All errors originating from the supabase.auth namespace of the JavaScript client library will be wrapped by the AuthError class.

Error objects are split in a few classes:

  • AuthApiError -- errors which originate from the Supabase Auth API.
    • Use isAuthApiError instead of instanceof checks to see if an error you caught is of this type.
  • CustomAuthError -- errors which generally originate from state in the client library.
    • Use the name property on the error to identify the class of error received.

Errors originating from the server API classed as AuthApiError always have a code property that can be used to identify the error returned by the server. The status property is also present, encoding the HTTP status code received in the response.

In general the HTTP status codes you will likely receive are:

  • 403 Forbidden is sent out in rare situations where a certain Auth feature is not available for the user, and you as the developer are not checking a precondition whether that API is available for the user.
  • 422 Unprocessable Entity is sent out when the API request is accepted, but cannot be processed because the user or Auth server is in a state where it cannot satisfy the request.
  • 429 Too Many Requests is sent out when rate-limits are breached for an API. You should handle this status code often, especially in functions that authenticate a user.
  • 500 Internal Server Error often means that the Auth server's service is degraded. Most often it points to issues in your database setup such as a misbehaving trigger on a schema, function, view or other database object.
  • 501 Not Implemented is sent out when a feature is not enabled on the Auth server, and you are trying to use an API which requires it.

To supplement HTTP status codes, Supabase Auth returns a string error code which gives you more insight into what went wrong. These codes are stable and can be used to present an internationalized message to your users.

CodeDescription
bad_code_verifierReturned from the PKCE flow where the provided code verifier does not match the expected one. Indicates a bug in the implementation of the client library.
bad_jsonUsually used when the HTTP body of the request is not valid JSON.
bad_jwtJWT sent in the Authorization header is not valid.
bad_oauth_callbackOAuth callback from provider to Auth does not have all the required attributes (state). Indicates an issue with the OAuth provider or client library implementation.
bad_oauth_stateOAuth state (data echoed back by the OAuth provider to Supabase Auth) is not in the correct format. Indicates an issue with the OAuth provider integration.
captcha_failedCaptcha challenge could not be verified with the captcha provider. Check your captcha integration.
conflictGeneral database conflict, such as concurrent requests on resources that should not be modified concurrently. Can often occur when you have too many session refresh requests firing off at the same time for a user. Check your app for concurrency issues, and if detected back off exponentially.
email_conflict_identity_not_deletableUnlinking this identity causes the user's account to change to an email address which is already used by another user account. Indicates an issue where the user has two different accounts using different primary email addresses. You may need to migrate user data to one of their accounts in this case.
email_existsEmail address already exists in the system.
email_not_confirmedSigning in is not allowed for this user as the email address is not confirmed.
email_provider_disabledSignups are disabled for email and password.
flow_state_expiredPKCE flow state to which the API request relates has expired. Ask the user to sign in again.
flow_state_not_foundPKCE flow state to which the API request relates no longer exists. Flow states expire after a while and are progressively cleaned up, which can cause this error. Retried requests can cause this error, as the previous request likely destroyed the flow state. Ask the user to sign in again.
identity_already_existsThe identity to which the API relates is already linked to a user.
identity_not_foundIdentity to which the API call relates does not exist, such as when an identity is unlinked or deleted.
insufficient_aalTo call this API, the user must have a higher Authenticator Assurance Level. To resolve, ask the user to solve an MFA challenge.
invite_not_foundInvite is expired or already used.
manual_linking_disabledCalling the supabase.auth.linkUser() and related APIs is not enabled on the Auth server.
mfa_challenge_expiredResponding to an MFA challenge should happen within a fixed time period. Request a new challenge when encountering this error.
mfa_factor_name_conflictMFA factors for a single user should not have the same friendly name.
mfa_factor_not_foundMFA factor no longer exists.
mfa_ip_address_mismatchThe enrollment process for MFA factors must begin and end with the same IP address.
mfa_verification_failedMFA challenge could not be verified -- wrong TOTP code.
mfa_verification_rejectedFurther MFA verification is rejected. Only returned if the MFA verification attempt hook returns a reject decision.
no_authorizationThis HTTP request requires an Authorization header, which is not provided.
not_adminUser accessing the API is not admin, i.e. the JWT does not contain a role claim that identifies them as an admin of the Auth server.
oauth_provider_not_supportedUsing an OAuth provider which is disabled on the Auth server.
otp_disabledSign in with OTPs (magic link, email OTP) is disabled. Check your sever's configuration.
otp_expiredOTP code for this sign-in has expired. Ask the user to sign in again.
over_email_send_rate_limitToo many emails have been sent to this email address. Ask the user to wait a while before trying again.
over_request_rate_limitToo many requests have been sent by this client (IP address). Ask the user to try again in a few minutes. Sometimes can indicate a bug in your application that mistakenly sends out too many requests (such as a badly written useEffect React hook).
over_sms_send_rate_limitToo many SMS messages have been sent to this phone number. Ask the user to wait a while before trying again.
phone_existsPhone number already exists in the system.
phone_not_confirmedSigning in is not allowed for this user as the phone number is not confirmed.
phone_provider_disabledSignups are disabled for phone and password.
provider_disabledOAuth provider is disabled for use. Check your server's configuration.
provider_email_needs_verificationNot all OAuth providers verify their user's email address. Supabase Auth requires emails to be verified, so this error is sent out when a verification email is sent after completing the OAuth flow.
reauthentication_neededA user needs to reauthenticate to change their password. Ask the user to reauthenticate by calling the supabase.auth.reauthenticate() API.
reauthentication_not_validVerifying a reauthentication failed, the code is incorrect. Ask the user to enter a new code.
same_passwordA user that is updating their password must use a different password than the one currently used.
saml_assertion_no_emailSAML assertion (user information) was received after sign in, but no email address was found in it which is required. Check the provider's attribute mapping and/or configuration.
saml_assertion_no_user_idSAML assertion (user information) was received after sign in, but a user ID (called NameID) was not found in it which is required. Check the SAML identity provider's configuration.
saml_entity_id_mismatch(Admin API.) Updating the SAML metadata for a SAML identity provider is not possible, as the entity ID in the update does not match the entity ID in the database. This is equivalent to creating a new identity provider, and you should do that instead.
saml_idp_already_exists(Admin API.) Adding a SAML identity provider that is already added.
saml_idp_not_foundSAML identity provider not found. Most often returned after IdP-initiated sign-in with an unregistered SAML identity provider in Supabase Auth.
saml_metadata_fetch_failed(Admin API.) Adding or updating a SAML provider failed as its metadata could not be fetched from the provided URL.
saml_provider_disabledUsing Enterprise SSO with SAML 2.0 is not enabled on the Auth server.
saml_relay_state_expiredSAML relay state is an object that tracks the progress of a supabase.auth.signInWithSSO() request. The SAML identity provider should respond after a fixed amount of time, after which this error is shown. Ask the user to sign in again.
saml_relay_state_not_foundSAML relay states are progressively cleaned up after they expire, which can cause this error. Ask the user to sign in again.
session_not_foundSession to which the API request relates no longer exists. This can occur if the user has signed out, or the session entry in the database was deleted in some other way.
signup_disabledSign ups (new account creation) is disabled on the server.
single_identity_not_deletableEvery user must have at least one identity attached to it, so deleting (unlinking) an identity is not allowed if it's the only one for the user.
sms_send_failedSending an SMS message failed. Check your SMS provider configuration.
sso_domain_already_exists(Admin API.) Only one SSO domain can be registered per SSO identity provider.
sso_provider_not_foundSSO provider not found. Check the arguments in supabase.auth.signInWithSSO().
too_many_enrolled_mfa_factorsA user can only have a fixed number of enrolled MFA factors.
unexpected_audience(Deprecated feature not available via Supabase JavaScript client.) The request's X-JWT-AUD claim does not match the JWT's audience.
unexpected_failureAuth service is degraded or a bug is present, without a specific reason.
user_already_existsUser with this information (email address, phone number) cannot be created again as it already exists.
user_bannedUser to which the API request relates has a banned_until property which is still active. No further API requests should be attempted until this field is cleared.
user_not_foundUser to which the API request relates no longer exists.
user_sso_managedWhen a user comes from SSO, certain fields of the user cannot be updated (like email).
validation_failedProvided parameters are not in the expected format.
weak_passwordUser is signing up or changing their password without meeting the password strength criteria. Use the AuthWeakPasswordError class to access more information about what they need to do to make the assword pass.

Tips for better error handling

  • Do not use string matching on error messages! Always use the name and code properties of error objects to identify the situation.
  • Although HTTP status codes generally don't change, they can suddenly change due to bugs, so avoid relying on them unless absolutely necessary.

Create a new user

Creates a new user.

  • By default, the user needs to verify their email address before logging in. To turn this off, disable Confirm email in your project.
  • Confirm email determines if users need to confirm their email address after signing up.
    • If Confirm email is enabled, the return value is the user and you won't be logged in automatically.
    • If Confirm email is disabled, the return value is null and you will be logged in instead.
  • 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.
  • To learn how to handle OTP links & OAuth refer to initializing
  • If signUpWith() 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.
Parameters
    provider
    REQUIRED
    Email or Phone

    The provider to use for the user's authentication. In this case Email or Phone.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    Email.Config.() -> Unit or Phone.Config.() -> Unit

    The configuration for signing in with Email or Phone.


val user = supabase.auth.signUpWith(Email) {
    email = "example@email.com"
    password = "example-password"
}

Listen to auth events

Listen to session changes.


supabase.auth.sessionStatus.collect {
    when(it) {
        is SessionStatus.Authenticated -> {
            println("Received new authenticated session.")
            when(it.source) { //Check the source of the session
                SessionSource.External -> TODO()
                is SessionSource.Refresh -> TODO()
                is SessionSource.SignIn -> TODO()
                is SessionSource.SignUp -> TODO()
                SessionSource.Storage -> TODO()
                SessionSource.Unknown -> TODO()
                is SessionSource.UserChanged -> TODO()
                is SessionSource.UserIdentitiesChanged -> TODO()
            }
        }
        SessionStatus.LoadingFromStorage -> println("Loading from storage")
        SessionStatus.NetworkError -> println("Network error")
        is SessionStatus.NotAuthenticated -> {
            if(it.isSignOut) {
                println("User signed out")
            } else {
                println("User not signed in")
            }
        }
    }
}

Create an anonymous user

  • Creates an anonymous user.
  • The user can be retrieved by calling supabase.auth.currentUserOrNull().
  • 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
    captchaToken
    Optional
    String?

    The captcha token when having captcha enabled.

    data
    Optional
    JsonObject? or T

    Extra user data to pass in.


supabase.auth.signInAnonymously(captchaToken = "token")

Sign in a user

Logs in an existing user.

  • Requires either an email and password or a phone number and password.
Parameters
    provider
    REQUIRED
    Email or Phone

    The provider to use for the user's authentication, in this case Email or Phone.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    Email.Config.() -> Unit or Phone.Config.() -> Unit

    The configuration for signing in with Email or Phone.


supabase.auth.signInWith(Email) {
    email = "example@email.com"
    password = "example-password"
}

Sign in with ID Token

Parameters
    provider
    REQUIRED
    IDToken

    The provider to use for the user's authentication. For this method it will be IDToken.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    IDToken.Config.() -> Unit

    The configuration for signing in with an id token.


supabase.auth.signInWith(IDToken) {
    idToken = "token"
    provider = Google //Also supported: Apple, Azure and Facebook
    //optional:
    nonce = "nonce"
    data = buildJsonObject {
        //...
    }
}

Sign in a user through OTP

Sends a OTP to the user's email or phone number.

  • 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, signInWith(OTP) will signup the user instead. To restrict this behavior, you can set createUser to false.
  • The method signUpWith(OTP) does the exact same thing as signInWith(OTP), so it doesn't matter which one you use.
  • 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.
  • To learn how to handle OTP links & OAuth refer to initializing
  • 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 }}.
Parameters
    provider
    REQUIRED
    OTP

    The provider to use for the user's authentication, in this case OTP.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    OTP.Config.() -> Unit

    The configuration for signing in with OTP.


supabase.auth.signInWith(OTP) {
    email = "example@email.com"
}

Sign in a user through OAuth

  • This method is used for signing in using a third-party provider.
  • Supabase supports many different third-party providers.
  • To learn how to handle OTP links & OAuth refer to initializing
Parameters
    provider
    REQUIRED
    OAuthProvider

    The OAuth provider to use for the user's authentication, for example Google or Github.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    ExternalAuthConfig.() -> Unit

    The configuration for signing in with an OAuth provider.


supabase.auth.signInWith(Github)

Sign in a user through SSO

  • 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 change the domain property in the signInWith(SSO) method 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 change 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.
  • To learn how to handle OTP links & OAuth refer to initializing
Parameters
    provider
    REQUIRED
    SSO

    The OAuth provider to use for the user's authentication, in this case SSO.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    ExternalAuthConfig.() -> Unit

    The configuration for signing in with an OAuth provider.


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

  supabase.auth.signInWith(SSO) {
      domain = "company.com"
  }

  //the url was opened automatically, if you don't want that, provide a custom redirect url

Sign out a user

Logs out the current user.

  • In order to use the signOut() method, the user needs to be signed in first.
Parameters
    scope
    Optional
    SignOutScope

    The scope of the sign-out.


supabase.auth.signOut()

Send a password reset request

Sends a password reset request to the given email address.

  • 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().
  • The user gets redirected back to your app, assuming you setup OTP handling
  • After the user has been redirected successfully, prompt them for a new password and call updateUser(): 
    1supabase.auth.updateUser {
2    password = "1234567"
3}
Parameters
    email
    REQUIRED
    String

    The email to send the password reset email to.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    captchaToken
    Optional
    String?

    The captcha token when having captcha enabled.


supabase.auth.resetPasswordForEmail(email = "example@email.com")

Verify and log in through OTP

  • Verifying an OTP is done through either verifyPhoneOtp or verifyEmailOtp.
  • The verification type used should be determined based on the corresponding auth method called before using verifyPhoneOtp/verifyEmailOtp to sign up / sign-in a user.
Parameters
    type
    REQUIRED
    OtpType.Email or OtpType.Phone

    The OTP type. Depending on the type, an email or phone has to be specified as parameter.

    email/phone
    REQUIRED
    String

    The email or phone number, depending on which type you specified.

    token
    REQUIRED
    String

    The token to verify.

    captchaToken
    Optional
    String?

    The captcha token when having captcha enabled.


supabase.auth.verifyEmailOtp(type = OtpType.Email.EMAIL, email = "example@email.com", token = "token")

Retrieve a session

Returns the current session, or null if there is none.


val session = supabase.auth.currentSessionOrNull()

Retrieve a new session

This method will refresh the session whether the current one is expired or not.

  • This is done automatically, but can be disabled in the Auth config.
Parameters
    refreshToken
    REQUIRED
    String

    The refresh token to use.


val session = supabase.auth.refreshCurrentSession()

Retrieve a user

  • This method gets the user object from the current session.
  • Fetches the user object from the database instead of local session.
  • Should be used only when you require the most current user data. For faster results, getCurrentSessionOrNull()?.user is recommended.
Parameters
    jwt
    REQUIRED
    String

    The JWT token.


val user = supabase.auth.retrieveUserForCurrentSession(updateSession = true)

Update a user

Modifies the user data.

  • 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
    updateCurrentUser
    Optional
    Boolean

    Whether to update the local session with the new user. Defaults to true.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    REQUIRED
    UserUpdateBuilder.() -> Unit

val user = supabase.auth.updateUser {
   email = "newEmail@email.com"
}

Retrieve identities linked to a user

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

//get the identities from the current user
val identities = supabase.auth.currentIdentitiesOrNull()
//Or retrieve them
val identities = supabase.auth.retrieveUserForCurrentSession().identities

Link an identity to a user

  • 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.
  • This method works similarly to signInWith() using an OAuthProvider. To learn how to handle OTP links & OAuth refer to initializing
Parameters
    provider
    REQUIRED
    OAuthProvider

    The OAuth provider you want to link the user with.

    redirectUrl
    Optional
    String?

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    ExternalAuthConfigDefaults.() -> Unit

    Extra configuration.


supabase.auth.linkIdentity(OAuthProvider)

//Example:
supabase.auth.linkIdentity(Google)

Unlink an identity from a user

  • 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
    identityId
    REQUIRED
    String

    The id of the OAuth identity

    updateLocalUser
    Optional
    Boolean

    Whether to delete the identity from the local user or not. Defaults to true.


//get all identities linked to a user
val identities = supabase.auth.currentIdentitiesOrNull() ?: emptyList()

//find the google identity linked to the user
val googleIdentity = identities.first { it.provider == "google" }

//unlink the google identity from the user
supabase.auth.unlinkIdentity(googleIdentity.identityId!!)

Send a password reauthentication nonce

  • This method is used together with updateUser() when a user's password needs to be updated.
  • 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.

supabase.auth.reauthenticate()

Resend an OTP

  • Resends a signup confirmation, email change or phone change email to the user.
  • Passwordless sign-ins can be resent by calling the signInWith(OTP) 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.
Parameters
    type
    REQUIRED
    OtpType.Email or OtpType.Phone

    The OTP type. Depending on the type, an email or phone has to be specified as parameter.

    email/phone
    REQUIRED
    String

    The email or phone number, depending on which type you specified.

    captchaToken
    Optional
    String?

    The captcha token when having captcha enabled.


supabase.auth.resendEmail(OtpType.Email.SIGNUP, "example@email.com")

Set the session data

Changes the local session.

  • importSession() takes in a UserSession.
  • Refresh token rotation is enabled by default on all projects to guard against replay attacks.
  • You can configure the REFRESH_TOKEN_REUSE_INTERVAL which provides a short window in which the same refresh token can be used multiple times in the event of concurrency or offline issues.
Parameters
    session
    REQUIRED
    UserSession

    The session to set.


supabase.auth.importSession(UserSession(accessToken = "token", refreshToken = "refresh", expiresIn = 2000, tokenType = "Bearer", user = null))

Exchange an auth code for a session

  • Used when flowType is set to FlowType.PKCE in the Auth configuration.
Parameters
    code
    REQUIRED
    String

    The code to exchange.

    saveSession
    Optional
    Boolean

    Whether to save the session. Defaults to true.


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

Auth MFA

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

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

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

Enroll a factor

Enrolls a new factor.

Parameters
    factorType
    REQUIRED
    FactorType<R>

    The type of MFA factor to enroll. Currently only supports FactorType.TOTP.

    issuer
    Optional
    String?

    Domain which the user is enrolling with.

    friendlyName
    Optional
    String?

    Human readable name assigned to a device.


val factor = supabase.auth.mfa.enroll(factorType = FactorType.TOTP)

// Use the id to create a challenge.
// The challenge can be verified by entering the code generated from the authenticator app.
// The code will be generated upon scanning the qr_code or entering the secret into the authenticator app.
val (id, type, qrCode) = factor.data //qrCode is a svg as a string
val (factorId, factorType, _) = factor

Create a challenge

Creates a challenge for a factor.

Parameters
    factorId
    REQUIRED
    String

    The id of the MFA factor you want to create a challenge for.


val challenge = supabase.auth.mfa.createChallenge(factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225")

Verify a challenge

Verifies a challenge for a factor.

Parameters
    factorId
    REQUIRED
    String

    The id of the MFA factor to verify.

    challengeId
    REQUIRED
    String

    The id of the challenge to verify.

    code
    REQUIRED
    String

    The code used to verify.

    saveSession
    Optional
    Boolean

    Whether to save the session. Defaults to true.


supabase.auth.mfa.verifyChallenge(
    factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225",
    challengeId = "4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15",
    code = "123456",
    saveSession = true // this is set to true by default, but you can set it to false if you want to handle the session yourself
)

Create and verify a challenge

Creates and verifies a challenge for a factor.

Parameters
    factorId
    REQUIRED
    String

    The id of the MFA factor to verify.

    code
    REQUIRED
    String

    The code used to verify.

    saveSession
    Optional
    Boolean

    Whether to save the session. Defaults to true.


supabase.auth.mfa.createChallengeAndVerify(
    factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225",
    code = "123456",
    saveSession = true // this is set to true by default, but you can set it to false if you want to handle the session yourself
)

Unenroll a factor

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

Parameters
    factorId
    REQUIRED
    String

    The id of the factor you want to unenroll.


supabase.auth.mfa.unenroll(factorId = "34e770dd-9ff9-416c-87fa-43b31d7ef225")

Get Authenticator Assurance Level

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

val (current, next) = supabase.auth.mfa.getAuthenticatorAssuranceLevel()

Auth Admin

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

val supabase = createSupabaseClient(
    supabaseUrl = "https://id.supabase.co",
    supabaseKey = "supabaseKey"
) {
    install(Auth) {
        minimalSettings() //disables session saving and auto-refreshing
    }
    // install other plugins (these will use the service role key)
}
supabase.auth.importAuthToken("service_role")

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

Retrieve a user

Fetches the user object from the database based on the user's id.

  • The retrieveUserById() method requires the user's id which maps to the auth.users.id column.
Parameters
    uid
    REQUIRED
    String

    The id of the user you want to retrieve.


val user = supabase.auth.admin.retrieveUserById(uid = "f2a0b0a0-6b1a-4b7a-8f1a-4b7a6b1a8f1a")

List all users

Retrieves a list of users.

  • Defaults to return 50 users per page.
Parameters
    page
    Optional
    Int

    The page number to retrieve.

    perPage
    Optional
    Int

    The number of users to retrieve per page.


val users = supabase.auth.admin.retrieveUsers()

Create a user

Creates a new user.

  • To confirm the user's email address or phone number, set autoConfirm to true. Both arguments default to false.
Parameters
    builder
    REQUIRED
    AdminUserBuilder.Email.() -> Unit or AdminUserBuilder.Phone.() -> Unit

    The builder to create a new user.


val userWithEmail = supabase.auth.admin.createUserWithEmail {
    email = "example@email.com"
    password = "secretpassword"
    userMetadata {
        put("name", "John")
    }
}

Delete a user

Deletes a user from the database.

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

    The id of the user you want to delete.


supabase.auth.admin.deleteUser(uid = "uid")

Send an email invite link

Sends an invite link to the user's email address.

Parameters
    email
    REQUIRED
    String

    The email to send the invite to.

    redirectTo
    Optional
    String

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    data
    Optional
    JsonObject

    Custom data to create the user with.


supabase.auth.admin.inviteUserByEmail(
    email = "example@email.com",
    //optional:
    redirectTo = "https://example.com/redirect",
    data = buildJsonObject {
        put("custom", "value")
    }
)

Generate an email link

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

Parameters
    type
    REQUIRED
    LinkType<C>

    The type of link to generate, e.g. LinkType.Signup.

    redirectTo
    Optional
    String

    The redirect url to use. If you don't specify this, the platform specific will be used, like deeplinks on android.

    config
    Optional
    C.() -> Unit

    The builder to create a new link.


val (url, user) = supabase.auth.admin.generateLinkFor(LinkType.Signup) {
    email = "example@email.com"
    password = "secretpassword"
}

Update a user

Updates the user data.

Parameters
    uid
    REQUIRED
    String

    The id of the user you want to update.

    builder
    REQUIRED
    AdminUserUpdateBuilder.() -> Unit

    The builder to update the user.


supabase.auth.admin.updateUserById(uid = "id") {
    email = "example@email.com"
}

List all factors for a user

Lists all factors associated to a user.

Parameters
    uid
    REQUIRED
    String

    The id of the user you want to list factors for.


const factors = supabase.auth.admin.retrieveFactors(uid = "id")

Delete a factor for a user

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

Parameters
    uid
    REQUIRED
    String

    The id of the user you want to delete a factor for.

    factorId
    REQUIRED
    String

    The id of the factor you want to delete.


supabase.auth.admin.deleteFactor(uid = "id", factorId = "factor_id")

Invokes a Supabase Edge Function.

Invokes a Supabase Function. See the guide for details on writing Functions.

  • When invoking a function with parameters, you have to provide a serializable value in the function parameter.
  • Requires an Authorization header.
Parameters
    function
    REQUIRED
    String

    The name of the function to invoke.

    body
    Optional
    T

    The body to send with the request. T can be any serializable type.

    region
    Optional
    FunctionRegion

    The region where the function is invoked. Defaults to Functions.Config#defaultRegion.

    headers
    Optional
    Headers

    The headers to send with the request.


supabase.functions.invoke("function_name")

Listen to database changes

Return real-time data from your table as a Flow.

  • Realtime is disabled by default for new tables. You can turn it on by managing replication.
  • selectAsFlow and selectSingleValueAsFlow will emit the initial data and then listen for changes.
  • Takes in a filter parameter to filter the data and a primaryKey parameter to cache the data by the primary key.
  • This method requires both the Realtime and Postgrest plugins to be installed.
  • The type parameter T must be a serializable class.
  • If you want more control over the realtime updates, you can use the Realtime plugin directly.
Parameters
    primaryKey
    REQUIRED
    KProperty1<Data, Value> or PrimaryKey<Data>

    The primary key to cache the data by. Can be a property reference or a custom primary key.

    channelName
    Optional
    String

    The name of the channel to use for the realtime updates. If null, a channel name following the format "schema:table:id" will be used

    filter
    Optional
    PostgrestFilterBuilder.() -> Unit or FilterOperation

    The filter to apply to the data.


val flow: Flow<List<Country>> = supabase.from("countries").selectAsFlow(Country::id)
flow.collect {
    for (country in it) {
        println(country.name)
    }
}

Subscribe to channel

Subscribe to realtime changes in your database.

  • Realtime is disabled by default for new Projects for better database performance and security. You can turn it on by managing replication.
  • If you want to receive the "previous" data for updates and deletes, you will need to set REPLICA IDENTITY to FULL, like this: ALTER TABLE your_table REPLICA IDENTITY FULL;
  • When using a method with a generic type like track, broadcast or broadcastFlow, you have to provide a serializable class as the type parameter.
  • Presence, Broadcast and Database updates are sent through a Flow

@Serializable
data class Message(val content: String, val sender: String)

val channel = supabase.channel("channelId") {
    //optional config
}

val broadcastFlow = channel.broadcastFlow<Message>(event = "message")

//Collect the flow
broadcastFlow.collect { //it: Message
    println(it)
}

channel.subscribe(blockUntilSubscribed = true)

channel.broadcast(event = "message", Message("I joined!", "John"))

Unsubscribe from a channel

Unsubscribes and removes Realtime channel from Realtime client.

  • Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes.
  • Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
  • If you removed all channels, the client automatically disconnects from the Realtime websocket. This can be disabled in the Realtime config by setting disconnectOnNoSubscriptions to false.

val channel = supabase.channel("channelId") {
    //optional config
}
//...
supabase.realtime.removeChannel(channel)

Unsubscribe from all channels

Unsubscribes and removes all Realtime channels from Realtime client.

  • Removing channels is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Supabase will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
  • If you removed all channels, the client automatically disconnects from the Realtime websocket. This can be disabled in the Realtime config by setting disconnectOnNoSubscriptions to false.

supabase.realtime.removeAllChannels()

Retrieve all channels

Returns all Realtime channels.


val channels = supabase.realtime.subscriptions.entries

Create a bucket

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

    The id of the bucket you want to create.

    builder
    Optional
    BucketBuilder.() -> Unit

    The builder to create a new bucket.


supabase.storage.createBucket(id = "icons") {
    public = true
    fileSizeLimit = 5.megabytes
}

Retrieve a bucket

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

val bucket = supabase.storage.retrieveBucketById(bucketId = "avatars")

List all buckets

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

val buckets = supabase.storage.retrieveBuckets()

Update a bucket

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

    The id of the bucket you want to create.

    builder
    Optional
    BucketBuilder.() -> Unit

    The builder to create a new bucket.


supabase.storage.updateBucket("cards") {
    public = false
    fileSizeLimit = 20.megabytes
    allowedMimeTypes(ContentType.Image.PNG, ContentType.Image.JPEG)
}

Delete a 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
    bucketId
    REQUIRED
    String

    The id of the bucket you want to delete.


supabase.storage.deleteBucket(bucketId = "icons")

Empty a 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
    bucketId
    REQUIRED
    String

    The id of the bucket you want to empty.


supabase.storage.emptyBucket(bucketId = "icons")

Upload a file

  • RLS policy permissions required:
    • buckets table permissions: none
    • objects table permissions: insert
  • Refer to the Storage guide on how access control works
  • Resumable uploads use a Disk cache by default to store the upload urls. You can customize that in the Auth config by changing the resumable.cache property.
Parameters
    path
    REQUIRED
    String

    The path of the file you want to upload.

    data
    REQUIRED
    ByteArray

    The data of the file you want to upload.

    upsert
    Optional
    Boolean

    Whether to overwrite the file if it already exists.


val bucket = supabase.storage.from("avatars")
bucket.upload("myIcon.png", byteArray, upsert = false)
//on JVM you can use java.io.File
bucket.upload("myIcon.png", file, upsert = false)

Download a file

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

    The path of the file you want to download.


val bucket = supabase.storage.from("avatars")
val bytes = bucket.downloadAuthenticated("test.png")
//or on JVM:
bucket.downloadAuthenticatedTo("test.png", File("test.png"))

List all files in a bucket

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

val bucket = supabase.storage.from("avatars")
val files = bucket.list()

Replace an existing file

  • 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
    path
    REQUIRED
    String

    The path of the file you want to upload.

    data
    REQUIRED
    ByteArray

    The data of the file you want to upload.

    upsert
    Optional
    Boolean

    Whether to overwrite the file if it already exists.


val bucket = supabase.storage.from("avatars")
bucket.update("myIcon.png", byteArray, upsert = false)
//on JVM you can use java.io.File
bucket.update("myIcon.png", file, upsert = false)

Move an existing file

  • 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
    from
    REQUIRED
    String

    The path of the file you want to move.

    to
    REQUIRED
    String

    The new path of the file.

    destinationBucket
    Optional
    String

    The destination bucket of the file.


val bucket = supabase.storage.from("avatars")
bucket.move("icon1.png", "icon2.png")

Copy an existing file

  • 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
    from
    REQUIRED
    String

    The path of the file you want to copy.

    to
    REQUIRED
    String

    The new path of the file.

    destinationBucket
    Optional
    String

    The destination bucket of the file.


supabase.storage.from("test").copy(from = "avatar.png", to = "avatar2.png")

Delete files in a bucket

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

    The paths of the files you want to remove.


val bucket = supabase.storage.from("avatars")
bucket.delete("test.png", "test2.png")

Create a signed URL

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

    The path of the file you want to create a signed url for.

    expiresIn
    REQUIRED
    Duration

    The duration the signed url should be valid for.

    builder
    Optional
    ImageTransformation.() -> Unit

    The transformation to apply to the image.


val bucket = supabase.storage.from("avatars")
val url = bucket.createSignedUrl(path = "icon.png", expiresIn = 3.minutes)

Create signed URLs

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

    The duration the signed url should be valid for.

    paths
    REQUIRED
    vararg String

    The paths of the files you want to create signed urls for.


val urls = supabase.storage.from("avatars").createSignedUrls(20.minutes, "avata1.jpg", "avatar2.jpg")

Create signed upload URL

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

    The path of the file you want to upload.


val url = supabase.storage.from("avatars").createSignedUploadUrl("avatar.png")

Upload to a signed URL

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

    The path of the file you want to upload.

    token
    REQUIRED
    String

    The token you received from createSignedUploadUrl.

    data
    Optional
    ByteArray

    The data of the file you want to upload.


supabase.storage.from("avatars").uploadToSignedUrl(path = "avatar.jpg", token = "token-from-createSignedUploadUrl", data = bytes)
//or on JVM:
supabase.storage.from("avatars").uploadToSignedUrl(path = "avatar.jpg", token = "token-from-createSignedUploadUrl", file = File("avatar.jpg"))

Retrieve public URL

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

    The path of the file you want to get the public url for.


val url = supabase.storage.from("public-bucket").publicUrl("folder/avatar1.png")