What you can do
- Approve operations with a passkey: run passkey enrollment and approval for Strong Customer Authentication (SCA) in a web application. Pair it with the Node.js SDK or the REST API on your backend.
Requirements
- Node.js 22 or later, for the build tools that install and bundle the package. The package is ECMAScript modules (ESM) only.
- Every origin that runs the ceremony, such as
https://app.example.com, registered in Circle Hub under Settings > Digital Asset Accounts > SCA, for sandbox and production. Circle doesn’t run a ceremony on an unregistered origin, includinglocalhost.
Install
Initialize
Methods
sca.enroll
Runs passkey enrollment. Call it once per end customer per device, with the
frame token from
POST /v1/accounts/passkeys/registrations.
attestationResponse to
POST /v1/accounts/passkeys.
sca.approve
Runs an approval for one protected operation, with the frame token from
POST /v1/accounts/passkeys/challenges.
X-Sca-Assertion header of the
protected request.
Safari, iPhone, and iPad browsers
Safari, and every browser on iOS and iPadOS, doesn’t run a passkey ceremony inside a cross-origin iframe. In those browsers,enroll and approve open
Circle’s page in a new window instead, and presentation shows nothing. A
browser opens that window only during the end customer’s click. Call enroll or
approve directly from the click handler, and pass the frame token as a promise
so that the SDK waits for your backend:
enroll or approve after an await, the browser blocks the
window and the call rejects with Unsupported. Don’t send the
Cross-Origin-Opener-Policy: same-origin header on the page, because it cuts
the window off from your page. same-origin-allow-popups works.
Parameters
enroll and approve take the same parameters:
Page requirements
The page that runs the ceremony must allow Circle’s iframe:- Content Security Policy: allow the ceremony origin in
frame-src, or inchild-src. Usehttps://daa-sca.circle.comfor production andhttps://daa-sca-sandbox.circle.comfor sandbox. - Inline styles: the modal adds one
<style>element without a nonce. If your policy restrictsstyle-src, allow it, or useinlinemode and style the container yourself. - Permissions Policy: the SDK sets the
allowattribute on the iframe forpublickey-credentials-get,publickey-credentials-create, andpayment. Don’t set it yourself. If your page sends aPermissions-Policyheader, it must not block those features for the ceremony origin. - Top-level page: run the ceremony on a page that isn’t inside another iframe. Each enclosing frame must grant the passkey permissions too, and a missing grant fails the same way as an end customer who declines.
- Cross-Origin-Opener-Policy: don’t send
same-originon a page that starts a ceremony.same-origin-allow-popupsworks. - Browser only: create the client and call
enrollorapprovein client-side code, not during server-side rendering.
Style the modal
The modal’s overlay, panel, and close button are part of your page. Style them with these classes. The SDK adds its own styles first, so your rules at the same specificity win.
The modal uses
z-index: 60. If another element on your page covers it, raise
the z-index of .circle-sca-modal.
Errors
enroll and approve throw ScaError. Check an error with isScaError, then
read err.code:
Errors from the calls that your backend makes, such as an unregistered origin
(420064), come from the API, not from this SDK. See the
Node.js SDK.
Versions
The SDK follows semantic versioning. Before version 1.0.0, a minor version can include breaking changes, so pin an exact version. The source is atcirclefin/daa-node-sdk, in
packages/web, with a changelog for each release.