Configuration

RakomiAuthConfiguration is the single entry point for configuring RakomiAuth. It is a value type (Sendable), so multiple configurations — different tenants, a test harness alongside your main app — can coexist as independent RakomiAuth instances; the SDK does not enforce a process-global singleton.

Constructing one

let configuration = try RakomiAuthConfiguration(
    publishableKey: "pk_live_acme",
    redirectURI: URL(string: "myapp://callback")!
)

The initializer throws synchronously — invalid configuration is a programmer error and must surface immediately, not later as a runtime auth failure on the authStateChanges stream.

Fields

Field	Type	Default	Notes
publishableKey	String	— (required)	Tenant-scoped publishable key, format pk_(test|live)_<...>. Must be non-empty.
redirectURI	URL	— (required)	Custom URL scheme for the OAuth callback. Ignored on tvOS, which uses the device authorization grant instead.
apiBaseURL	URL	https://api.rakomi.com	Override for self-managed / on-prem deployments. Must be https://, with one narrow local-development exception — see below.
issuer	URL	https://api.rakomi.com	The expected JWT iss claim. This is the platform identifier and is independent of apiBaseURL — even a custom-domain tenant receives tokens with this issuer, because a custom domain is routing only. Override for multi-issuer test harnesses.
jwksURL	URL	{apiBaseURL}/.well-known/jwks.json	Override if your deployment serves JWKS elsewhere.
keychainAccessGroup	String?	nil	Set to share stored credentials across an app extension or app group.
freshAuthWindow	TimeInterval	30	Accepted for forward compatibility; no code path reads it today. It gates nothing and skips nothing — setting it, including to 0, changes no behavior. A biometric prompt is available on demand through the SDK’s unlockWithBiometric(reason:) call (see Session & tokens), which is an additional path into hydration, not a gate in front of it.
certificateFingerprints	[String]?	nil	Optional SHA-256 certificate pins, applied to the https:// requests the SDK issues. Accepts base64 (canonical), hex, or colon-separated hex — all are normalized before comparison. nil or empty disables pinning.
audience	String?	https://api.rakomi.com	Expected JWT aud claim, independent of apiBaseURL. Override for multi-issuer test harnesses.

What the initializer validates

The initializer throws an SdkError (see Errors) — never a bare Error — on:

• publishableKey empty.
• apiBaseURL not acceptable. The scheme must be https, with one exception for local development: http is accepted only when the host is exactly localhost, or a dotted-quad IPv4 address in 127.0.0.0/8 or 10.0.0.0/8. The exception is anchored on strict host equality / IPv4 form — a hostname that merely contains one of these strings is rejected. 10.0.0.0/8 is a private LAN range, not loopback — traffic to it leaves the device, so treat this exception as a development convenience only, never point a production build at a plaintext http:// address.
• redirectURI scheme forbidden. On every platform except tvOS (which does not use redirectURI), the scheme may be anything except http, https, javascript, data, file, vbscript, or about.
• A malformed certificateFingerprints entry. A pin that cannot be normalized into any of the three accepted forms can never match, so it is rejected at configuration time rather than causing every pinned connection to fail later with what would look like an active MITM.

Deriving a tenant id

configuration.tenantId extracts the tenant id from publishableKey when it follows the pk_(test|live)_<tenantId> format; if the key doesn’t match that shape, it falls back to a stable digest of the key so local storage namespacing stays consistent across app launches.

Next steps

• Authentication — use the configuration to sign a user in.
• Errors — the full SdkErrorCode / SdkErrorReason taxonomy.