> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DAA web SDK reference

> SDK reference for the DAA web SDK package, which runs the Strong Customer Authentication ceremony in your web application.

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](/digital-asset-accounts/howtos/strong-customer-authentication).

## Install

```shell theme={null}
npm install @circle-fin/daa-web-sdk
```

## `createScaClient`

Creates an SCA client bound to the given environment.

```typescript theme={null}
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`.

```typescript theme={null}
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.

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

***

## `sca.approve`

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

```typescript theme={null}
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.

```typescript theme={null}
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.          |