Digital Asset Accounts iOS SDK

The iOS SDK is available in sandbox only. Production support is on the roadmap.

The iOS SDK runs in your application on the end customer’s iPhone. It never holds your API key and makes no calls to the Circle API itself. Your backend does that and passes your application only the short-lived token for one ceremony.

What you can do

Approve operations with a passkey: run passkey enrollment and approval for Strong Customer Authentication (SCA) in a Swift application.
Hold the authorization key for non-custodial accounts: the React Native SDK calls this SDK to create the end customer’s authorization key in the Secure Enclave and sign with it. You don’t call these methods yourself. To build a non-custodial account integration, use the React Native SDK.

Requirements

Requirement	Minimum
Swift	5.9
Xcode	15.3
iOS, to install the SDK and hold the authorization key	15.0
iOS, for passkey enrollment and approval	17.4

Passkey enrollment and approval need iOS 17.4 or later, because Circle accepts only https callback URLs, which ASWebAuthenticationSession supports from iOS 17.4. On earlier versions, or in an app built with Xcode earlier than 15.3, DaaScaConfiguration throws DaaScaConfigurationError.httpsCallbackUnavailable. If you serve end customers who need Strong Customer Authentication, check for this error and tell the end customer to update iOS before they can approve an operation.

Install

Swift Package Manager
CocoaPods

Add the package to your Package.swift, or add it in Xcode under File > Add Package Dependencies:

dependencies: [
    .package(url: "https://github.com/circlefin/daa-ios-sdk.git", exact: "0.7.1"),
]

Then add the DaaSdk product to your application target.

Add Circle’s spec repository to your Podfile before the CocoaPods CDN source, then add the pod:

source "https://github.com/circlefin/daa-ios-sdk.git"
source "https://cdn.cocoapods.org/"

pod "DaaSdk", "0.7.1"

pod install

Set up the callback

When a ceremony finishes, Circle’s page returns the result to your application through an app callback URI. Set it up once for each environment:

Choose an https callback URL on a domain that you control, such as https://app.example.com/sca/callback. The SDK refuses a URL that includes a port or an IP address. Circle doesn’t accept custom schemes.
Register every exact callback URL that you use in Circle Hub, under Settings > Digital Asset Accounts > SCA. Register separately in sandbox and production.
Add a webcredentials: entry for the host to your application’s Associated Domains, and serve the matching apple-app-site-association file.

Your backend sends the same callback URL as redirectUri when it opens each passkey registration or challenge. It replaces embedOrigin, which applies only to web pages. If the value doesn’t exactly match a registered URL, Circle returns error code 420068.

Initialize

Create a DaaSca with a DaaScaConfiguration:

import DaaSdk

let sca = DaaSca(configuration: try DaaScaConfiguration(
    environment: .sandbox,
    redirectURI: "https://app.example.com/sca/callback"
))

Parameter	Required	Description
`environment`	Yes	`.sandbox` or `.production`
`redirectURI`	Yes	Your registered callback URL, exactly as registered. Up to 2,048 characters
`approveTimeout`	No	How long an approval can take, in seconds. Defaults to 300. Must be from 30 to 3,600
`enrollTimeout`	No	How long an enrollment can take, in seconds. Defaults to 600. Must be from 30 to 3,600

An invalid value throws DaaScaConfigurationError.

Methods

DaaSca runs on the main actor. Its ceremony methods are async and present Circle’s page in an ASWebAuthenticationSession sheet.

Method	Returns	Description
`enroll(frameToken:)`	`String`	Runs passkey enrollment. Send the returned registration response to your backend unchanged
`approve(frameToken:)`	`String`	Runs an approval. Your backend sends the returned value, unchanged, in the `X-Sca-Assertion` header
`enroll(frameToken:presentationAnchor:)`	`String`	Same as `enroll(frameToken:)`, presented over the window that you pass
`approve(frameToken:presentationAnchor:)`	`String`	Same as `approve(frameToken:)`, presented over the window that you pass
`capabilities()`	`DaaScaCapabilities`	Reports whether this device can run a ceremony. `isCeremonySupported` is `true` when the sheet, callback, and passkeys are available

Without an anchor, the SDK presents over the key window of the foreground scene. Pass an anchor when your application has more than one window, such as on iPad. One ceremony runs at a time: starting another one, or cancelling the Swift Task, cancels the open ceremony. This example approves a transfer. Your backend opens the challenge, returns only the frame token, and later sends the transfer with the assertion:

func approveTransfer(_ transferId: String) async {
    do {
        let frameToken = try await backend.startTransfer(transferId)
        let assertion = try await sca.approve(frameToken: frameToken)
        // Send the assertion exactly as returned. Don't parse or re-encode it.
        try await backend.confirmTransfer(transferId, assertion: assertion)
    } catch DaaScaError.cancelled {
        // The end customer closed the sheet. Let them try again.
    } catch {
        // See Errors.
    }
}

For the backend steps, see How-to: Implement Strong Customer Authentication.

Errors

The ceremony methods throw DaaScaError:

Case	Cause	What to do
`cancelled`	The end customer closed the sheet, or another ceremony replaced this one	Let them try again
`expired(message:)`	The frame token or the ceremony timed out	Ask your backend for a new frame token
`alreadyEnrolled(message:)`	The end customer already has a passkey on this device	Skip enrollment
`unsupported(message:)`	The device can’t run the ceremony, for example because passkeys aren’t available	Check `capabilities()`
`sessionUnavailable(message:)`	The sheet couldn’t be shown: there’s no window to present over, or this iOS version can’t deliver the callback	Check your callback setup, or pass a `presentationAnchor`
`stateMismatch`	The callback didn’t belong to the open ceremony	An integration bug. Don’t retry automatically
`protocol`(message:)	The ceremony returned an unexpected result, such as an invalid frame token	An integration bug. Don’t offer a different authentication method instead

message is for your logs. Don’t show it to the end customer.

Versions

The SDK follows semantic versioning. Before version 1.0.0, a minor version can include breaking changes, so pin an exact version. If you also use the React Native SDK, use the iOS SDK version that it pins.

Developer-controlled wallets

User-controlled wallets

Modular wallets