Swift Reference v2.0

Swift Client Library

@supabase/supabase-swift

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

Installing

Install using Swift Package Manager

You can install Supabase package using Swift Package Manager.

The package exposes multiple libraries, you can choose between adding all of them using Supabase, or some of:

  • Auth
  • Realtime
  • Postgrest
  • Functions
  • Storage

_21
let package = Package(
_21
...
_21
dependencies: [
_21
...
_21
.package(
_21
url: "https://github.com/supabase/supabase-swift.git",
_21
from: "2.0.0"
_21
),
_21
],
_21
targets: [
_21
.target(
_21
name: "YourTargetName",
_21
dependencies: [
_21
.product(
_21
name: "Supabase", // Auth, Realtime, Postgrest, Functions, or Storage
_21
package: "supabase-swift"
_21
),
_21
]
_21
)
_21
]
_21
)

Initializing

You can initialize Supabase with the SupabaseClient by passing your Project URL and Project Key. You can find these under your Project SettingsAPI Settings The Supabase client is your entrypoint to the rest of the Supabase functionality and is the easiest way to interact with everything we offer within the Supabase ecosystem.


let client = SupabaseClient(supabaseURL: URL(string: "https://xyzcompany.supabase.co")!, supabaseKey: "public-anon-key")

Fetch data

  • By default, Supabase projects will return a maximum of 1,000 rows. This setting can be changed in Project 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 Modifiers
  • select() can be combined with Filters
  • If using the Supabase hosted platform apikey is technically a reserved keyword, since the API gateway will pluck it out for authentication. It should be avoided as a column name.
  • The recommended solution for getting data is to use the value property which will return a decoded model. Create a Codable to easily decode your database responses.

struct Country: Decodable {
  let id: Int
  let name: String
}

let countries: [Country] = try await supabase
  .from("countries")
  .select()
  .execute()
  .value

Insert data


struct Country: Encodable {
  let id: Int
  let name: String
}

let country = Country(id: 1, name: "Denmark")

try await supabase
  .from("countries")
  .insert(country)
  .execute()

Update data

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

try await supabase
  .from("countries")
  .update(["name": "Australia"])
  .eq("id", value: 1)
  .execute()

Upsert data

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

struct Country: Encodable {
  let id: Int
  let name: String
}
try await supabase
  .from("countries")
  .upsert(Country(id: 1, name: "Albania"))
  .execute()

Delete data

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

try await supabase
  .from("countries")
  .delete()
  .eq("id", value: 1)
  .execute()

Call a Postgres function

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

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

let value: String = try await supabase
  .rpc("hello_world")
  .execute()
  .value

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.

Implement URLQueryRepresentable protocol in your own types to be able to use them as filter value.

Supported filtes are: eq, neq, gt, gte, lt, lte, like, ilike, is, in, cs, cd, sl, sr, nxl, nxr, adj, ov, fts, plfts, phfts, wfts. Check available operators in PostgREST.


try await supabase
  .from("cities")
  .select("name, country_id")
  .eq("name", value: "The Shire")    // Correct

try await supabase
  .from("citites")
  .eq("name", value: "The Shire")    // Incorrect
  .select("name, country_id")

Match an associated value


try await supabase
  .from("countries")
  .select("name")
  .match(["id": 2, "name": "Albania"])

Don't match the filter

Finds all rows that don't satisfy the filter.

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

    1.not("name", operator: .eq, value: "Paris")
    2.not("arraycol", operator: .cs, value: #"{"a","b"}"#) // Use Postgres array {} for array column and 'cs' for contains.
    3.not("rangecol", operator: .cs, value: "(1,2]") // Use Postgres range syntax for range column.
    4.not("id", operator: .in, value: "(6,7)")  // Use Postgres list () and 'in' for in_ filter.
    5.not("id", operator: .in, value: "(\(mylist.join(separator: ",")))")  // You can insert a Swift list array.

try await supabase
  .from("countries")
  .select()
  .not("name", operator: .is, value: "")
  .execute()

Match at least one filter

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

try await supabase
  .from("countries")
  .select("name")
  .or("id.eq.2,name.eq.Algeria")

Match the filter

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

1.filter("id", operator: .in, value: "(5,6,7)")  // Use `()` for `in` filter
2.filter("arraycol", operator: .cs, value: #"{"a","b"}"#)  // Use `cs` for `contains()`, `{}` for array values

try await supabase
  .from("countries")
  .select()
  .filter("name", operator: .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 must be specified after filters. Some modifiers only apply for queries that return rows (e.g., select() or rpc() on a function that returns a table response).

Return data after inserting

Perform a SELECT on the query result.


  try await supabase
    .from("countries")
    .upsert(CountryModel(id: 1, name: "Algeria"))
    .select()
    .execute()

Order the results

Order the query result by column.


try await supabase
  .from("countries")
  .select("id, name")
  .order("id", ascending: false)
  .execute()

Limit the number of rows returned

Limit the query result by count.


try await supabase
  .from("countries")
  .select("id, name")
  .limit(1)
  .execute()

Limit the query to a range

Limit the query result by from and to inclusively.


try await supabase
  .from("countries")
  .select(
    """
      name,
      cities (
        name
      )
    """
  )
  .range(from: 0, to: 1)
  .execute()

Retrieve one row of data

By default PostgREST returns all JSON results in an array, even when there is only one item, use single() to return the first object unenclosed by an array.


try await supabase
  .from("countries")
  .select("name")
  .limit(1)
  .single()
  .execute()

Retrieve as a CSV


try await supabase
  .from("countries")
  .select()
  .csv()
  .execute()

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.


try await supabase
  .from("countries")
  .select()
  .explain()
  .execute()
  .value

Overview

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

UIKit app lifecycle

1public func application(
2  _ application: UIApplication,
3  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
4) -> Bool {
5  if let url = launchOptions?[.url] as? URL {
6    supabase.auth.handle(url)
7  }
8
9  return true
10}
11
12func application(
13  _ app: UIApplication,
14  open url: URL,
15  options: [UIApplication.OpenURLOptionsKey: Any]
16) -> Bool {
17  supabase.auth.handle(url)
18  return true
19}
20
21#### UIKit app lifecycle with scenes
22
23In your `SceneDelegate.swift`:
24
25```swift
26func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
27  guard let url = URLContexts.first?.url else { return }
28  supabase.auth.handle(url)
29}

SwiftUI app lifecycle

In your AppDelegate.swift:

1SomeView()
2  .onOpenURL { url in
3    supabase.auth.handle(url)
4  }

let supabase = SupabaseClient(supabaseURL: URL(string: "https://xyzcompany.supabase.co")!, supabaseKey: "public-anon-key")
let 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

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

try await supabase.auth.signUp(
  email: "example@email.com",
  password: "example-password"
)

Listen to auth events

  • Subscribes to important events occurring on the user's session.
  • 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.
      • 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.
    • 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.session 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.update(user:) 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.


// Using AsyncStream
for await (event, session) in await supabase.auth.authStateChanges {
  print(event, session)
}

// Using Closure
let subscription = await supabase.auth.onAuthStateChange { event, session in 
  print(event, session)
}

// call remove() to remove subscription
subscription.remove()

Create an 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.

let session = try await supabase.auth.signInAnonymously(captchaToken: captchaToken)

Sign in a user

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

try await supabase.auth.signIn(
  email: "example@email.com",
  password: "example-password"
)

Sign in with ID Token


let session = try await supabase.auth.signInWithIdToken(
  credentials: OpenIDConnectCredentials(
    provider: .apple,
    idToken: "your-id-token",
    nonce: "your nonce"
  )
)

Sign in a user through OTP

  • Requires either an email or phone number.
  • This method is used for passwordless sign-ins where a OTP is sent to the user's email or phone number.
  • If the user doesn't exist, signInWithOTP() will signup the user instead. To restrict this behavior, you can set shouldCreateUser 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.

try await supabase.auth.signInWithOTP(
  email: "example@email.com",
  redirectTo: URL(string: "my-app-scheme://")!
)

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.

let session = try await supabase.auth.signInWithOAuth(
  provider: .github
) { (session: ASWebAuthenticationSession) in 
  // customize session
}

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

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

  let url = try await await supabase.auth.signInWithSSO{
    domain: "company.com"
  }

  // Open the URL using your preferred method to complete sign-in process.
  UIApplication.shared.open(url)

Sign out a user

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

try await supabase.auth.signOut()

Verify and log in through OTP

  • The verifyOTP method takes in different verification types. If a phone number is used, the type can either be sms or phone_change. If an email address is used, the type can be one of the following: signup, magiclink, recovery, invite, email_change, or email.
  • The verification type used should be determined based on the corresponding auth method called before verifyOTP to sign up / sign-in a user.

try await supabase.auth.verifyOTP(
  phone: "+13334445555",
  token: "123456",
  type: .sms
)

Retrieve a session

  • Returns the session, refreshing it if necessary. If no session can be found, a GoTrueError.sessionNotFound error is thrown.

try await supabase.auth.session

Retrieve a new session

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

let session = try await supabase.auth.refreshSession()

Retrieve a user

  • This method is useful for checking if the user is authorized because it validates the user's access token JWT on the server.
  • 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, session.user is recommended.

let user = try await supabase.auth.user()

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

try await supabase.auth.update(user: UserAttributes(email: "new@email.com"))

Retrieve identities linked to a user

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

let identities = try await supabase.auth.userIdentities()

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.

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.

Send a password reauthentication nonce

  • This method is used together with update(user:) 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.

try await 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 signInWithOTP() method again.
  • Password recovery emails can be resent by calling the resetPasswordForEmail() method again.
  • This method only resends an email or phone OTP to the user if there an initial signup, email change, or phone change request was made.
  • You can specify a redirect URL when you resend an email link using the emailRedirectTo option.

try await supabase.auth.resend(
  email: "email@example.com",
  type: .signup,
  emailRedirectTo: URL(string: "my-app-scheme://")
)

Set the session data

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

  try await supabase.auth.setSession(accessToken: "access_token", refreshToken: "refresh_token")

Exchange an auth code for a session

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

try await supabase.auth.exchangeCodeForSession(authCode: "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

  • Currently, totp is the only supported factorType. The returned id should be used to create a challenge.
  • To create a challenge, see mfa.challenge().
  • To verify a challenge, see mfa.verify().
  • To create and verify a challenge in a single step, see mfa.challengeAndVerify().

let response = try await supabase.auth.mfa.enroll(
  params: MFAEnrollParams(
    issuer: "optional issuer",
    friendlyName: "optional friendly name"
  )
)

// Use the id to create a challenge.
// The challenge can be verified by entering the code generated from the authenticator app.
// The code will be generated upon scanning the qrCode or entering the secret into the authenticator app.
let id = response.id
let type = response.type
let qrCode = response.totp?.qrCode
let secret = response.totp?.secret
let uri = response.totp?.uri

Create a challenge


let response = try await supabase.auth.mfa.challenge(
  params: MFAChallengeParams(
    factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225"
  )
)

Verify a challenge


let session = try await supabase.auth.mfa.verify(
  params: MFAVerifyParams(
    factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225",
    challengeId: "4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15",
    code: "123456"
  )
)

Create and verify a challenge


let session = try await supabase.auth.mfa.challengeAndVerify(
  params: MFAChallengeAndVerifyParams(
    factorId: "34e770dd-9ff9-416c-87fa-43b31d7ef225",
    code: "123456"
  )
)

Unenroll a factor


let response = try await supabase.auth.mfa.unenroll(
  params: MFAUnenrollParams(
    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 nextLevel field will return aal2, else, it will return aal1.

let aal = try await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
let currentLevel = aal.currentLevel
let nextLevel = aal.nextLevel
let currentAuthenticationMethods = aal.currentAuthenticationMethods

Auth Admin

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

import Supabase

let supabase = SupabaseClient(
  supabaseURL: supabaseURL,
  supabaseKey: serviceRoleKey
)

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

Delete a user

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

try await supabase.auth.admin.deleteUser(
  id: "715ed5db-f090-4b8c-a067-640ecee36aa0"
)

List all factors for a user


let factors = try await supabase.auth.mfa.listFactors()

Invokes a Supabase Edge Function.

Invoke a Supabase Edge Function.

  • Requires an Authorization header.
  • When you pass in a body to your function, we automatically attach the Content-Type header for String, and Data. 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 behaviour by passing in a Content-Type header of your own.

struct Response: Decodable {
  // Expected response definition
}

let response: Response = try await supabase.functions
  .invoke(
    "hello", 
    options: FunctionInvokeOptions(
      body: ["foo": "bar"]
    )
  )

Subscribe to channel

  • 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.
  • Use AsyncStream or callbacks for listening to changes.

let channel = await supabase.channel("room1")

let broadcastStream = await channel.broadcastStream(event: "cursor-pos")

await channel.subscribe()

Task {
  for await message in broadcastMessage {
    print("Cursor position received", message.payload)
  }
}

Task {
  await channel.broadcast(
    event: "cursor-pos",
    message: [
      "x": .double(.random(in: 0...1)),
      "y": .double(.random(in: 0...1))
    ]
  )
}

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.

let channel = await supabase.channel("channelId") 

//...
await supabase.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.

await supabase.removeAllChannels()

Retrieve all channels

Returns all Realtime channels.


let channels = await supabase.channels

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

try await supabase.storage
  .createBucket(
    "avatars", 
    options: BucketOptions(
      public: false,
      allowedMimeTypes: ["image/png"],
      fileSizeLimit: 1024
    )
  )

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

let bucket = try await supabase.storage
  .getBucket("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

try await supabase.storage
  .listBuckets()

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

try await supabase.storage
  .updateBucket(
    "avatars", 
    options: BucketOptions(
      public: false,
      fileSizeLimit: 1024,
      allowedMimeTypes: ["image/png"]
    )
  )

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

try await supabase.storage
  .deleteBucket("avatars")

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

try await supabase.storage
  .emptyBucket("avatars")

Upload a file

  • 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

let fileName = "avatar1.png"

try await supabase.storage
  .from("avatars")
  .upload(
    path: "public/\(fileName)",
    file: fileData,
    options: FileOptions(
      cacheControl: "3600",
      contentType: "image/png",
      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

let data = try await supabase.storage
  .from("avatars")
  .download(path: "folder/avatar1.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

let files = try await supabase.storage
  .from("avatars")
  .list(
    path: "folder",
    options: SearchOptions(
      limit: 100,
      offset: 0,
      sortBy: SortBy(column: "name", order: "asc")
    )
  )

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

let fileName = "avatar1.png"

try await supabase.storage
  .from("avatars")
  .update(
    path: "public/\(fileName)",
    file: fileData,
    options: FileOptions(
      cacheControl: "3600",
      contentType: "image/png",
      upsert: true
    )
  )

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

try await supabase
  .storage
  .from("avatars")
  .move(from: "public/avatar1.png", to: "private/avatar2.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

try await supabase
  .storage
  .from("avatars")
  .copy(from: "public/avatar1.png", to: "private/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

try await supabase.storage
  .from("avatars")
  .remove(paths: ["folder/avatar1.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

let signedURL = try await supabase.storage
  .from("avatars")
  .createSignedURL(path: "folder/avatar1.png", expiresIn: 60)

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

let urls = try await supabase
  .storage
  .from("avatars")
  .createSignedURLs(paths: ["folder/avatar1.png", "folder/avatar2.png"], expiresIn: 60)

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

let publicURL = try supabase.storage
  .from("public-bucket")
  .getPublicURL(path: "folder/avatar1.png")