Skip to main content
Check whether an end customer requires SCA, enroll a passkey for them, then obtain a signed approval for each sensitive operation and submit it alongside the API request. For what an approval proves and why the ceremony runs on a Circle-hosted page, see How Strong Customer Authentication works.
Implement SCA if you serve end customers in the European Economic Area (EEA). Whether SCA applies depends on each end customer, not on your platform. Check each end customer, as described in step 1.
The SCA ceremony runs on a Circle-hosted page. In a web application, the web SDK embeds it in an iframe. In an iOS or Android application, the iOS, Android, or React Native SDK opens the same page in the system authentication browser (ASWebAuthenticationSession on iOS, an Auth Tab or Custom Tab on Android), and the page returns the result to your application at an app callback URI.
Don’t run the ceremony in a web view. Your application could script the page and change the operation the end customer approves.

Prerequisites

Before you begin, ensure that you’ve:
  • Registered where the ceremony runs, in Circle Hub under Settings > Digital Asset Accounts > SCA. Register separately in sandbox and production:
    • For a web application, the web origin: scheme and host, for example https://app.example.com.
    • For an iOS or Android application, the app callback URI, for example https://app.example.com/sca/callback. It must use https on your domain: an Android App Link, or on iOS a webcredentials Associated Domain (not applinks), which needs iOS 17.4 or later.
    Changing these lists needs the Digital Asset Accounts manage role and an MFA step-up. They can’t be changed with an API key.
  • Installed the client-side SDK for your application’s platform: the web, React Native, iOS, or Android SDK.
  • Obtained a clientEntityId for the end customer you’re enrolling. See Onboard customers for how to create one.
  • Run a device check for the end customer and stored the deviceId it returned. See Collect device risk signals. Every protected operation sends that deviceId in riskSignals.
Reuse the deviceId returned by checkDevice(). Do not generate one. Circle resolves it against the completed device check, and an unrecognized value is accepted and then declined: the endpoint returns 201 and the transaction later settles as failed.

Steps

Step 1. Check whether the end customer requires SCA

List the end customer’s passkeys with GET /v1/accounts/passkeys. The response carries both the SCA requirement and the passkeys already enrolled:
Response
The list includes revoked passkeys. An end customer has an active passkey when at least one entry has revokedDate set to null. Use sca.required to decide what to do before a protected operation: If sca is null, don’t store it. Call the endpoint as usual and handle HTTP 428 if it’s returned. Handle a 428 even when sca.required is false. For what each value means, whether you can store it, and how voluntary SCA works, see Which end customers require SCA.

Step 2. Enroll a passkey

Enroll a passkey for each end customer who requires SCA, before they run any protected operation. Run this flow once per end customer, and again if they revoke their last active passkey or can’t access it on a new device.
If you haven’t registered any origin, the request to create a registration session fails with HTTP 400 and error code 420064. If embedOrigin doesn’t exactly match a registered origin, or you leave it out while you have more than one, the request fails with HTTP 400. If your page runs on an origin other than the one you registered, such as localhost, the ceremony fails. Register each origin, for sandbox and production, before running this flow.
Native application: add redirectUri to the request body in step 2.1 and step 3.1, set to your registered app callback URI. Circle matches it exactly, including case and any trailing slash. An unregistered or malformed value fails with HTTP 400 and error code 420068, and no frame token is issued. Don’t send embedOrigin in the same request.

Step 2.1. Create a registration session

Set embedOrigin to the origin of the page that runs the ceremony. Send it on every request from a web application.
Response
The frame token expires after 10 minutes. Pass it to your frontend right away. Do not re-send the request with the same idempotencyKey after delivering the token. This rotates the token and invalidates the copy you already sent. Start a fresh session with a new idempotencyKey if the token expires.

Step 2.2. Run the enrollment ceremony

Pass the frame token from step 2.1 to your application, and run the enrollment with the SDK for its platform.
In Safari, and in every browser on iOS and iPadOS, call enroll directly from the click handler, and pass the frame token as a promise instead of awaiting your backend first. See Safari, iPhone, and iPad browsers.
Send the result to your backend without changing any of its fields. A changed field causes a verification error. The React Native, iOS, and Android SDKs return it as JSON text: your backend parses it once and sends the parsed object as attestationResponse.

Step 2.3. Complete the registration

Send the attestationResponse from the SDK to your backend. Then forward it to Circle to complete enrollment.
Response

Step 3. Approve a protected operation

For every protected operation, obtain a signed challenge and include it in the API request.

Step 3.1. Create a challenge

Generate the transfer’s idempotency key first. The challenge intent and the transfer in step 3.3 must carry the same key, so run both requests in the same shell session.
Response
The summary is a server-generated record of the operation. Don’t use it to render a pre-confirmation to the end customer, because Circle’s page shows its own description to the end customer.
The frame token expires after 5 minutes. Pass it to your frontend right away. Each request creates a new challenge, and an earlier challenge stays valid until it’s used or expires. If the token expires, create a new challenge with the same intent.
The intent must be identical to the operation request body: same fields, same values. An extra or missing field causes an intent mismatch error (420047). For the full list of intent shapes by operation, see the Create a challenge API reference. Set operation to match the endpoint you are about to call: TRANSFER, WITHDRAWAL, ADDRESS_BOOK_ADD, ADDRESS_BOOK_DELETE, or WIRE_ACCOUNT_CREATE. ADDRESS_BOOK_DELETE is the one exception. That endpoint takes no request body, so send an empty intent and put the address ID in pathParameters:
The idempotencyKey in the intent must match the idempotencyKey in the operation request body. A mismatch causes an intent mismatch error.

Step 3.2. Run the approval ceremony

Pass the frameToken from the challenge response to your application, and run the approval with the SDK for its platform. Each SDK returns the assertion as a string.
In Safari, and in every browser on iOS and iPadOS, call approve directly from the click handler, and pass the frame token as a promise. See Safari, iPhone, and iPad browsers.
Send the assertion to your backend as a string. Don’t re-serialize it.

Step 3.3. Submit the protected operation

Include the challengeId and assertion as request headers. Use the same field values you set in the challenge intent.
Response
201 means the operation was accepted, not that it succeeded. A transfer is screened after it is created and can settle as failed. Poll GET /v1/accounts/transfers/{id} until status is terminal, and read errorCode and riskEvaluation on that response to see why, for example errorCode: transfer_denied with riskEvaluation.decision: denied. The list endpoint omits riskEvaluation, so fetch the transfer by id. A declined device check or an unrecognized deviceId surfaces here, not on the create call.
If the request was rejected before the transfer was created, the endpoint returns an error instead of 201.
If a protected endpoint returns HTTP 428 (error code 420058), the X-Sca-Challenge-Id or X-Sca-Assertion header was omitted from the request. Circle requires SCA for this end customer. If they have no active passkey, enroll one (step 2) first. Then run the approval ceremony and retry with both headers present. HTTP 503 with error code 420059 means Circle couldn’t determine whether SCA applies. Retry the request, and don’t treat it as “SCA not required.” For other SCA errors, see the Digital Asset Accounts API reference.