Integrate Strong Customer Authentication in a web app
Learn how to run Strong Customer Authentication (SCA) from your web app, for both signing in (OAuth) and consenting to sensitive operations.
Swan opens SCA in the user's browser. Your web app redirects the user to a Swan URL, Swan handles authentication, then Swan redirects the user back to a URL you own.
Don't open Swan's authorization, consent, or sensitive card information pages:
- In an iframe
- In a WebView
- In a popup (for example, with
window.open)
Swan no longer supports these flows, and they stop working from 31 December 2026.
Instead, redirect the user to the URL:
- On the web, in the current browser tab.
- In a mobile app, in the device's browser or an in-app browser tab (
SFSafariViewControlleron iOS, Chrome Custom Tabs on Android).
How it works
- Your server gets a Swan URL: the authorization URL for sign-in, or the
consentUrlreturned by a sensitive operation. - Your web app redirects the user to that URL in the current tab.
- The user completes SCA. On a phone, they do it in the same tab. On a computer, Swan's page asks for their phone number, sends them an SMS with a link, and shows a "Check your phone" message while they confirm or cancel on the phone.
- Swan redirects the tab to your redirect URL with query parameters. On a computer, this happens automatically once the user finishes on their phone. They don't need to do anything in the tab.
- Your server checks the result with the Swan API, then shows the user the next step.
Sign in with OAuth
Follow the Get a user access token guide to build the authorization URL and exchange the code.
On the web, send the user to the authorization URL with a plain redirect:
// Server: build the URL, then redirect the user's browser to it
app.get("/auth", (req, reply) => {
const params = new URLSearchParams({
client_id: "$YOUR_CLIENT_ID",
response_type: "code",
redirect_uri: "https://my-company.com/auth/callback", // registered in your Dashboard
scope: "openid offline",
state: generateUserState(req),
});
return reply.redirect(`https://oauth.swan.io/oauth2/auth?${params}`);
});
Swan sends the user back to redirect_uri with code and state in the query string. Check that state matches before exchanging the code.
Consent to a sensitive operation
This example uses the viewCardNumbers mutation. The same flow applies to every sensitive operation.
Step 1: Get the consent URL
Call the mutation with a user access token, setting consentRedirectUrl to a page on your site.
app.post("/cards/:cardId/numbers", async (req, reply) => {
const { consentUrl } = await swanClient.viewCardNumbers({
input: {
cardId: req.params.cardId,
consentRedirectUrl: "https://my-company.com/cards/callback",
},
});
return reply.json({ consentUrl });
});
Step 2: Redirect the user
In the browser, redirect in the current tab.
const { consentUrl } = await fetch("/cards/123/numbers", { method: "POST" }).then((r) => r.json());
window.location.assign(consentUrl);
Step 3: Handle the redirect back
After SCA, Swan redirects the user to consentRedirectUrl and adds these query parameters:
consentId.env:SandboxorLive.status:Accepted,CustomerRefused,OperationCommitting,Created,Started,Expired,Failed, orCanceled.resourceId, if the consent only impacts one resource.
The status parameter is informational. Always confirm the consent with the API before acting on it.
query GetConsentStatus {
consent(id: "$YOUR_CONSENT_ID") {
id
status
updatedAt
}
}
app.get("/cards/callback", async (req, reply) => {
const { consent } = await swanClient.getConsentStatus({ id: req.query.consentId });
if (consent.status !== "Accepted") {
return reply.redirect("/cards?error=consent");
}
return reply.redirect("/cards?numbers=shown");
});
Good to know
- Consent links time out 20 minutes after being opened. Request a new
consentUrlif the user comes back later. - For card numbers, the
consentUrlonly works in the browser where it was opened, even if the user confirms SCA on their phone. The same URL doesn't work in another browser or in a private window. For five minutes after the user consents, you can reopen the sameconsentUrlwithout repeating SCA. - Use the
stateparameter on OAuth redirects to protect against Cross-Site Request Forgery (CSRF).