Docs
⌘K

Swift SDK

Install the Swift SDK, create a client, handle errors, and find every type and method by area.

Updated Oct 24, 2026

The Sovaria client for iOS, macOS, tvOS, watchOS and Linux: async/await and Foundation only, with no third-party dependencies. It has the same surface as the Dart, Kotlin, TypeScript and Python clients.

#Install

.package(url: "https://github.com/sovaria/sovaria-swift.git", from: "1.0.0")

#Create a client

Use the project URL and the anon key from the console's Connect panel. The anon key is public and safe to ship in an app. Never put the service role key in a mobile app. For a full walkthrough see iOS quickstart (Swift).

import Sovaria

let sovaria = try await Sovaria.initialize(
    url: "https://<project-ref>.sovarias.in",
    anonKey: "<anon-key>",
    storage: KeychainStore()          // your SessionStorage; the default keeps the session in memory
)
try await sovaria.auth.signInWithPassword(email: "ada@example.com", password: "Correct-Horse-9!")

#Errors

Failed calls throw with the server's machine-readable code (for example PLAN_LIMIT_REACHED or INVALID_QUERY) and a readable message. See Troubleshooting.

do {
    _ = try await sovaria.db.sql("select * from orders")
} catch let error as SovariaError {
    print(error.code, error.message)   // e.g. PLAN_LIMIT_REACHED; error.status is the HTTP status
}

#Reference by area

AuthenticationSign app users in with passwords, magic links, SMS and email codes, OAuth/SSO and passkeys; keep and refresh the session; handle deep links.DatabaseRun SQL with bound parameters and select, insert, update, delete and call database functions.DocumentsRead, write and query document collections, count and aggregate, and commit several writes at once.StorageUpload, download, list and remove files, and create signed and public URLs.FunctionsInvoke your deployed functions.RealtimeJoin channels, send and receive messages, follow connection status and catch up after a reconnect.OfflineCache reads and queue writes while the device is offline, then sync in order; kept on disk by default.Firestore-compatible APIFirebase-style collection, document and query references on top of Sovaria documents, for moving a Firebase app over.Push, attestation and crashesRegister devices for push, prove requests come from your real app, and report crashes.SimulationCheck who can do what in your project without changing anything.Full API (api.*)Every Sovaria API operation as a typed call, grouped by module,.

#Client

Sovaria

The Sovaria client for Swift (iOS, macOS, Linux).

public final class Sovaria: Transport, @unchecked Sendable

Sovaria.baseURL

A property.

public let baseURL: String

Sovaria.anonKey

The project's public (anon) key: used for every request while nobody is signed in.

public let anonKey: String

Sovaria.storage

A property.

public let storage: SessionStorage

Sovaria.sessionKey

A property.

public let sessionKey: String

Sovaria.device

A property.

public let device: SovariaDevice?

Sovaria.retries

A property.

public let retries: Int

Sovaria.retryBaseDelay

A property.

public let retryBaseDelay: TimeInterval

Sovaria.refreshMargin

A property.

public let refreshMargin: TimeInterval

Sovaria.api

A property.

public let api: GeneratedApi

Sovaria.auth

A property.

public let auth: SovariaAuth

Sovaria.db

A property.

public let db: SovariaDatabase

Sovaria.files

A property.

public let files: SovariaStorage

Sovaria.functions

A property.

public let functions: SovariaFunctions

Sovaria.realtime

A property.

public let realtime: SovariaRealtime

Sovaria.crashes

A property.

public let crashes: SovariaCrashes

Sovaria.simulate

Simulation (team members): who can do what in the live project, with nothing written.

public let simulate: SovariaSimulation

Sovaria.push

Push notification tokens for the signed-in user.

public let push: SovariaPush

Sovaria.collections

Document collections (Firestore-style).

public let collections: SovariaCollections

Sovaria.offline

A property.

public var offline: SovariaOffline?

Sovaria.orgId

A property.

public var orgId: String?

Sovaria.projectId

A property.

public var projectId: String?

Sovaria.envId

A property.

public var envId: String?

Sovaria.Sovaria.init

Create an instance.

public init(url: String, anonKey: String, orgId: String? = nil, projectId: String? = nil, envId: String? = nil,
            storage: SessionStorage? = nil, device: SovariaDevice? = nil, attestation: AttestationProvider? = nil,
            urlSession: URLSession = .shared, retries: Int = 3, retryBaseDelay: TimeInterval = 0.2, refreshMargin: TimeInterval = 60,
            storageKey: String = "")

Sovaria.initialize

Create the client and restore the stored session (if any).

public static func initialize(url: String, anonKey: String, orgId: String? = nil, projectId: String? = nil,
                              envId: String? = nil, storage: SessionStorage? = nil, device: SovariaDevice? = nil,
                              attestation: AttestationProvider? = nil, urlSession: URLSession = .shared) async throws -> Sovaria

Sovaria.setScope

public func setScope(orgId: String? = nil, projectId: String? = nil, envId: String? = nil)

Sovaria.enableOffline

Turn on offline-first for the data API: writes made with no network are queued and replayed in order on reconnect; db.select/reads fall back to the last cached result.

public func enableOffline(store: OfflineStore = FileOfflineStore(), namespace: String? = nil,
                          onSyncError: (@Sendable (SovariaError, [String: Any]) -> Void)? = nil,
                          onSynced: (@Sendable (Int) -> Void)? = nil) -> SovariaOffline

Returns the controller.

The queue and cache are kept in files in Application Support by default (FileOfflineStore), so writes made offline still sync after the app is closed and reopened. Pass store: MemoryOfflineStore() to keep them for this run only.

Sovaria.scope

public func scope(_ name: String) -> String?

Sovaria.resolveScope

Learn the org/project behind the project URL (), once.

public func resolveScope() async

Sovaria.call

public func call(_ method: String, _ path: String, body: Any?, query: [String: Any?]?, auth: Bool) async throws -> Any?

Sovaria.request

Send one request and decode the JSON answer.

public func request(_ method: String, _ path: String, body: Any? = nil, query: [String: Any?]? = nil,
                    auth: Bool = true, headers: [String: String]? = nil, bytes: Data? = nil,
                    contentType: String? = nil, raw: Bool = false) async throws -> Any?

Signs with the session (refreshed near expiry, and once more after a 401) or the anon key; retries transient failures with backoff. Returns parsed JSON, or Data when raw is true.

SovariaError

An error answer from Sovaria (or a client-side problem such as missing configuration). Mirrors the Dart/TypeScript/Python clients: a machine-readable code (PLAN_LIMIT_REACHED, PKCE_REQUIRED, APP_ATTESTATION_REQUIRED…) plus the HTTP status (0 for network/config errors).

public struct SovariaError: Error, CustomStringConvertible

SovariaError.status

A property.

public let status: Int

SovariaError.code

A property.

public let code: String

SovariaError.message

A property.

public let message: String

SovariaError.details

A property.

public let details: Any?

SovariaError.traceId

A property.

public let traceId: String?

SovariaError.SovariaError.init

Create an instance.

public init(status: Int, message: String, code: String = "", details: Any? = nil, traceId: String? = nil)

SovariaError.isUnauthorized

A property.

public var isUnauthorized: Bool

SovariaError.isPlanLimit

A property.

public var isPlanLimit: Bool

SovariaError.needsAttestation

A property.

public var needsAttestation: Bool

SovariaError.description

A property.

public var description: String

SovariaError.config

A client-side configuration problem (no request was made).

public static func config(_ message: String) -> SovariaError

Transport

What the generated API needs from a client: send one request, and know the default scope.

public protocol Transport: AnyObject

Transport.call

Send method path with an optional JSON body and query; returns the decoded JSON.

func call(_ method: String, _ path: String, body: Any?, query: [String: Any?]?, auth: Bool) async throws -> Any?

Transport.scope

The client's default org_id / project_id / env_id, or nil.

func scope(_ name: String) -> String?

Related

Swift SDKiOS quickstart (Swift)JavaScript SDK