Skip to main content
The web SDK runs in the end customer’s browser. It never holds your API key. Your backend opens each ceremony with Circle and passes your page only the short-lived frame token for it. The SDK shows Circle’s passkey page in an iframe and returns the result.

What you can do

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, including localhost.

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.
Your backend passes the result as attestationResponse to POST /v1/accounts/passkeys.
Send the enrollment result to your backend as JSON. Don’t change, decode, or re-encode any of its field values. They’re signed, so any change causes a verification error.

sca.approve

Runs an approval for one protected operation, with the frame token from POST /v1/accounts/passkeys/challenges.
Your backend sends the assertion in the 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:
If you call 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 in child-src. Use https://daa-sca.circle.com for production and https://daa-sca-sandbox.circle.com for sandbox.
  • Inline styles: the modal adds one <style> element without a nonce. If your policy restricts style-src, allow it, or use inline mode and style the container yourself.
  • Permissions Policy: the SDK sets the allow attribute on the iframe for publickey-credentials-get, publickey-credentials-create, and payment. Don’t set it yourself. If your page sends a Permissions-Policy header, 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-origin on a page that starts a ceremony. same-origin-allow-popups works.
  • Browser only: create the client and call enroll or approve in client-side code, not during server-side rendering.
Circle’s page always shows “Secured by Circle” next to the approve button, and you can’t hide or restyle anything inside the iframe. If the ceremony can’t load, for example because the frame token expired, Circle’s page shows the end customer what to do. Your page isn’t notified, so offer a way to start again, such as closing the modal and opening a new ceremony.

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 at circlefin/daa-node-sdk, in packages/web, with a changelog for each release.