DAA web SDK reference

The DAA web SDK handles the client-side Strong Customer Authentication (SCA) ceremony for Digital Asset Accounts. Your backend creates a frame token through the Circle API; the SDK uses that token to render the WebAuthn passkey prompt in a Circle-hosted iframe and return the signed result. For a step-by-step integration guide, see How-to: Implement Strong Customer Authentication.

Install

npm install @circle-fin/daa-web-sdk

`createScaClient`

Creates an SCA client bound to the given environment.

import { createScaClient } from "@circle-fin/daa-web-sdk";

const sca = createScaClient({ environment: "sandbox" });

Parameters

Parameter	Type	Required	Description
`options.environment`	`"sandbox" \| "production"`	Yes	Determines which Circle-hosted iframe origin to load.

Returns

An ScaClient instance with enroll and approve methods.

`sca.enroll`

Runs the passkey enrollment ceremony. Call this once per end user per device, using the frame token from POST /v1/accounts/passkeys/registrations.

const attestationResponse = await sca.enroll(frameToken, { mode: "modal" });

Parameters

Parameter	Type	Required	Description
`frameToken`	`string`	Yes	Opaque token returned by `POST /v1/accounts/passkeys/registrations`.
`presentation.mode`	`"modal" \| "inline"`	Yes	`"modal"` renders the ceremony in an overlay. `"inline"` renders it inside a container element you provide.
`presentation.container`	`unknown`	Yes (inline only)	The container element to mount the ceremony into. Required when `mode` is `"inline"`.
`options.signal`	`AbortSignal`	No	Cancels the ceremony when aborted. The promise rejects with `code: 'Cancelled'`.

Returns

attestationResponse: a structured object representing the signed WebAuthn attestation. Pass it to your backend and forward it to POST /v1/accounts/passkeys unchanged.

Do not re-serialize attestationResponse before forwarding it to your backend. Re-serialization alters the binary encoding and causes a verification error.

`sca.approve`

Runs the operation approval ceremony. Call this for every protected operation, using the frame token from POST /v1/accounts/passkeys/challenges.

const assertion = await sca.approve(frameToken, { mode: "modal" });

Parameters

Parameter	Type	Required	Description
`frameToken`	`string`	Yes	Opaque token returned by `POST /v1/accounts/passkeys/challenges`.
`presentation.mode`	`"modal" \| "inline"`	Yes	`"modal"` renders the ceremony in an overlay. `"inline"` renders it inside a container element you provide.
`presentation.container`	`unknown`	Yes (inline only)	The container element to mount the ceremony into. Required when `mode` is `"inline"`.
`options.signal`	`AbortSignal`	No	Cancels the ceremony when aborted. The promise rejects with `code: 'Cancelled'`.

Returns

assertion: a string. Pass it to your backend and include it as the X-Sca-Assertion header on the protected API request.

Error handling

Both enroll and approve throw if the ceremony fails or the frame token is invalid. Wrap calls in try/catch and surface errors to the end user.

try {
  const assertion = await sca.approve(frameToken, { mode: "modal" });
} catch (err) {
  // Show an error state and allow the user to retry
}

Common failure causes:

DAA error code	Numeric code	Cause	What to do
`CEREMONY_CONSUMED_OR_EXPIRED`	420057	Frame token already used or expired (10 min enrollment / 5 min challenge).	Fetch a new token from your backend and retry.
`CEREMONY_TOKEN_REQUIRED`	420056	Frame token missing or malformed.	Ensure you pass the `frameToken` exactly as returned by the backend.
`SCA_ORIGIN_NOT_CONFIGURED`	420064	Your application origin is not registered.	Contact your support team to register the origin before running any ceremony.
`Cancelled`	—	User dismissed the ceremony or a cancel signal fired.	Prompt the user to try again, or handle the cancellation gracefully.

Developer-controlled wallets

User-controlled wallets

Modular wallets

Digital Asset Accounts

Contracts

Gateway Nanopayments

Migration guides

DAA web SDK reference

Install

`createScaClient`

Parameters

Returns

`sca.enroll`

Parameters

Returns

`sca.approve`

Parameters

Returns

Error handling

​Install

​createScaClient

​Parameters

​Returns

​sca.enroll

​Parameters

​Returns

​sca.approve

​Parameters

​Returns

​Error handling

Install

`createScaClient`

Parameters

Returns

`sca.enroll`

Parameters

Returns

`sca.approve`

Parameters

Returns

Error handling