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.
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.
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 usehttpson your domain: an Android App Link, or on iOS awebcredentialsAssociated Domain (notapplinks), which needs iOS 17.4 or later.
- For a web application, the web origin: scheme and host, for example
- Installed the client-side SDK for your application’s platform: the web, React Native, iOS, or Android SDK.
-
Obtained a
clientEntityIdfor 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
deviceIdit returned. See Collect device risk signals. Every protected operation sends thatdeviceIdinriskSignals.
Steps
Step 1. Check whether the end customer requires SCA
List the end customer’s passkeys withGET /v1/accounts/passkeys.
The response carries both the SCA requirement and the passkeys already enrolled:
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.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
SetembedOrigin to the origin of the page that runs the ceremony. Send it on
every request from a web application.
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.- Web
- React Native
- iOS
- Android
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 theattestationResponse from the SDK to your backend. Then forward it to
Circle to complete enrollment.
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.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.
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:
Step 3.2. Run the approval ceremony
Pass theframeToken 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.
- Web
- React Native
- iOS
- Android
approve directly from
the click handler, and pass the frame token as a promise. See
Safari, iPhone, and iPad browsers.Step 3.3. Submit the protected operation
Include thechallengeId and assertion as request headers. Use the same field
values you set in the challenge intent.
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.