Configuration

FolioSdk.create(config, mapper) takes a FolioSdkConfig. It is read once, when the runtime is created; to change it, close the runtime and create a new one. Each runtime configures its own logging writers. See Runtime and stores.

ExampleCopy Anchor Link

let config = FolioSdkConfig(
    baseUrl: "https://app.folio.mobi",
    organization: "<organization>",
    development: nil,
    logging: try FolioSdk.loggingConfig(consoleLevel: nil)
)

A production app passes no development configuration: nil in Swift, null (the default) in Kotlin and undefined in TypeScript. In Swift and TypeScript, pass every field, including the optional ones.

How each platform builds the three types:

FolioSdkConfigCopy Anchor Link

baseUrlCopy Anchor Link

The origin of the Folio backend, for example https://app.folio.mobi. The SDK builds every service address as baseUrl followed by /api/ and the service name, such as https://app.folio.mobi/api/inquiry. It also fetches the inquiry signing keys from <baseUrl>/.well-known/jwks.json. Give the origin without a trailing slash and without a path.

On the web, baseUrl is also the Folio backend origin, never your page's origin: the SDK signs each request for the address it builds from baseUrl, and Folio accepts that signature only for its own address. Call registerPageProxiedApiOrigin(baseUrl) before you create the runtime; the browser then sends those requests to the same paths on your page's origin, which forwards them to Folio. See Route API requests.

organizationCopy Anchor Link

The name of the organization your vault records belong to. The SDK stores the records your IdentityRecordMapper returns, and the records you write through the vault store, under this organization. The schema of a record you write is your own name for the document, without the organization; the SDK adds it. You never set or read the organization on a record.

Validation:

• It must not be empty.
• It may contain only lowercase letters a to z, digits 0 to 9 and the hyphen -.

Any other value makes create fail with the Core case of SessionStartError and the CoreError InvalidInput. See Start failures.

loggingCopy Anchor Link

The writers of the SDK's log journal for this runtime. FolioSdk.loggingConfig(consoleLevel) builds the usual value: a file writer at TRACE with the default journal limits and, when you pass a level, a console writer at that level. On the web, call it after initializeFolioWasm has resolved. A writer listed twice, or journal limits out of range, makes create fail with the CoreError LogsUnavailable. See Logging.

DevelopmentConfigCopy Anchor Link

realmCopy Anchor Link

Set, the SDK sends the realm in the X-Realm header of its authentication and session requests, its notification and vault requests, and its inquiry requests, including those of the verification steps (one-time code, government ID, NFC and selfie). Unset, like a missing development, the SDK sends no X-Realm header.

serviceEnvironmentsCopy Anchor Link

Each ServiceEnvironment moves one service to a development environment: the SDK addresses it at <baseUrl>/api/<service>-<environment> instead of <baseUrl>/api/<service>. A service without an entry keeps its regular address; an empty list keeps every service at its regular address.

The SDK sends no request to the wallet service; an entry for it changes no address, but it is validated like any other entry.

An environment is non-empty and contains only lowercase letters a to z, digits 0 to 9 and the hyphen -. An invalid environment, or a service listed twice, makes create fail with the CoreError InvalidInput.

const development: DevelopmentConfig = {
    realm: undefined,
    serviceEnvironments: [{ service: SdkService.V_GOV_ID_NFC, environment: 'feature-x' }],
};

Application identityCopy Anchor Link

The configuration carries no application identity. The SDK reads your application's identifier, version and build from the platform when create runs, and create fails with the CoreError NotInitialized when one of them is missing or blank.

The version and the build must each be at most 128 bytes of printable ASCII text, because the SDK sends them in a header. A longer value, or one with other characters, makes create fail with the CoreError InvalidInput. A build of the SDK without build stamps (SdkProduct Unstamped, see Versions and build info) does not check these values and sends no X-Folio-User-Agent, so a missing value does not make its create fail. In every build, the version and the build also reach Folio in the device footprint the SDK sends when it starts a session.

On the web, pass the identity when you load the wasm. A web application uses its origin as the identifier. initializeFolioWasm rejects a field that is not a non-empty string:

await initializeFolioWasm({
    source: manifestUrl,
    application: { identifier: window.location.origin, version: '2.3.4', build: '567' },
    load: () => loadFolioSDKWasm({ manifestUrl }),
});

The SDK reports the version and build to Folio in the X-Folio-User-Agent header of every request, next to the SDK version and the platform; the identifier stays on the device. See Versions and build info.