Skip to main content

Embedded flow

This guide shows you how to set up an integration with SMS OTP, using the Signicat Authentication REST API with embedded flow.

An embedded flow allows you to include the authentication flow inside an iframe in your application (as opposed to the redirect flow where you are redirecting the user to another page).

In an embedded flow, the authentication journey happens inside a component, like an iframe, embedded within your UI. In this scenario, your application manages the iframe and the end-user redirect, creating a hybrid integrated experience.

How it works​

The Signicat Authentication REST API enables you to create embedded flows for user authentication. This approach is designed to be rendered within an iframe, allowing the end-user to complete an authentication journey without leaving your application.

Iframe​

The <iframe> HTML tag allows you to embed the authentication flow in your application. You achieve this by passing the authentication URL in the <iframe> HTML tag, as shown below:

<!-- Replace the src with the authentication URL returned by the Authentication REST API -->
<iframe 
    src="https://api.signicat.com/idps/otp/sms?lang=en&transactionId=661...&messageId=f08..." 
    width="450"
    height="650">
</iframe>
What is an iframe?
What is an iframe?

An <iframe> (Inline Frame) is an HTML element that allows you to embed another HTML document within the current one.

<!-- The parent page (index.html) -->
<iframe src="iframe-content.html" width="450" height="650"></iframe>

The width and height attributes on the <iframe> tag control the size of the window that displays the child page. The child page itself has no inherent knowledge of these dimensions.

Flow​

The diagram below shows how the embedded authentication flow with SMS OTP works:

Sequence diagram showing embedded authentication with SMS OTP

Prerequisites​

  1. Follow the steps on the Configure SMS OTP page to establish a connection with SMS OTP.

  2. Before you can start making requests to the Authentication REST API, you need to learn how to connect to it. To do this, see Connect to Signicat APIs Quick start guide.

    Ensure that you set the Authentication REST API permission for your API client. When you have obtained an access token and are ready to make an API request, return here to resume this guide.

    Learn more about the Signicat Authentication REST API

Implementation​

This section details how to set up authentication for SMS OTP using the embedded flow.

In an authentication flow, your application shows your end-user the SMS OTP service for secure authentication and receives the end-user's personal information that you can later process further.

When implementing the embedded flow, your application requests an authentication URL and passes it to the end-user in an iframe. The authentication URL opens the authentication journey inside your application's UI.

Step 1. Create a session​

To initiate an authentication flow, you need to send a request to the Signicat Authentication REST API and create a session. This is similar to the redirect flow but requires specific properties in the session request payload. Once initiated, the authentication flow is completed within an iframe embedded into the your application.

Request​

To create a session in the Authentication REST API, you send a POST request to the Create a new session endpoint. The /sessions endpoint is where you create a new session to begin an authentication flow. This is https://api.signicat.com/auth/rest/sessions.

For example, your request could look like this:

curl --location 'https://api.signicat.com/auth/rest/sessions' \
--header 'Authorization: Bearer eyJ...' \
--header 'Content-Type: application/json' \
--data '{
    "allowedProviders": [
        "otp-sms"
    ],
    "flow": "embedded",
    "requestedAttributes": [
        "idpId",
        "phoneNumber"
    ],
    "returnUrl": "https://www.example.com",
    "embeddedParentDomains": ["www.w3schools.com"]
}'

Consider the following fields in the payload of the request:

Include embeddedParentDomains

When creating an authentication session with the Authentication REST API, you can configure the frame-ancestors directive by using the embeddedParentDomains parameter. It is strongly recommended that you set the embeddedParentDomains to the address of your Signicat domain (for example, app.example.com).

If you omit the embeddedParentDomains parameter, the frame-ancestors directive defaults to *. This means the browser will allow the OTP pages to be embedded into any website, leaving the OTP embedded flow vulnerable to malicious websites and clickjacking attacks.

For a complete overview of the supported query parameters, see the Create a session endpoint in the API reference.

You can find an overview of attributes and responses for SMS OTP in the Attributes for the Authentication REST API documentation.

Additional parameters​

When sending requests to the Signicat Authentication REST API, you can customise end-user authentication with the additionalParameters field. The key-values you define in the additionalParameters field vary depending on the eID.

SMS OTP supports the following parameters:

Example in a request payload:

    ...
    {
    "additionalParameters": {
        "otp_sms_sender": "Signicat AS"
    }
    }
    ...
Display SMS OTP only

To direct the end-user to SMS OTP, skipping the eIDs selection screen, you can use the "allowedProviders": ["otp-sms"] parameter in the payload of your request. This prevents users from choosing other eIDs that may be active in your account.

Response​

After sending a request to create a session, you receive a response that contains:

  • Metadata about your request.
  • A unique session ID to track process.
  • The authenticationUrl with a link for end-user authentication. You need to pass the authentication URL in the iframe so that the end-user can authenticate themselves.

Here is an example response after you have created a session:

{
    "id": "558b1459-335c-4431-8561-b44d9c727bb9",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://api.signicat.com/idps/otp/sms?lang=en&transactionId=661...messageId=f08...",
    "status": "CREATED",
    "allowedProviders": [
        "otp-sms"
    ],
    "flow": "embedded",
    "requestedAttributes": [
        "idpId",
        "phoneNumber"
    ],
    "sessionLifetime": 1200
}

Consider the following properties:

  • id: The unique identifier for the authentication session you just created. You will need this ID for any subsequent API calls related to this specific session, such as checking its status.
  • accountId: Your Signicat account that made the request.
  • authenticationUrl: The unique URL that you must use as the src attribute for the <iframe> in your web application. When you embed this URL, it will display the SMS OTP login interface to your user.
  • status: The current status of the session.
    • CREATED: This means the session has been successfully created on Signicat's servers, but the end-user has not yet started the authentication process within the iframe.
  • sessionLifetime: The time, in seconds, that the session will remain valid. The session will expire at the end of this timeframe.

Use the response​

Now, you need to pass the authenticationUrl returned in the response to the end-user in an iframe. This is a unique URL which allows the end-user to perform the SMS OTP authentication in context of the session you just created.

Example of an iframe using the authentication URL:

<iframe
  src="https://api.signicat.com/idps/otp/sms?lang=en&transactionId=661...&messageId=f08..."
  width="450"
  height="650">
</iframe>
Iframe size requirements

To ensure that all SMS OTP pages are framed correctly, make sure you set the following minimum dimensions:

  • Min size is 350px x 600px
  • Recommended min size for desktop devices is 450px x 650px

Step 2. Test an authentication​

You can quickly test the embedded flow without building a custom frontend application. To do this, start an authentication session with the Authentication REST API and pass the iframe in an online HTML tester, such as the W3Schools Tryit Editor. The next steps show how to test this feature in a custom HTML test page.

  1. Go to this project in the W3Schools Tryit Editor.
    Template HTML code

    To test the flow on a minimal HTML page, use the template HTML code below:

    <!DOCTYPE html>
    <html>
    <body>

    <h2>HTML Iframes</h2>
    <p>An iframe is used to display a web page within a web page:</p>

    <iframe src="demo_iframe.htm" width="450" height="650"></iframe>

    </body>
    </html>
  2. In the template HTML code, edit the <iframe> HTML tag and enter the authenticationUrl as value of the src attribute. 
    <iframe
        src="<AUTHENTICATION_URL>"
        width="450"
        height="650">
    </iframe>
  3. On the top navigation bar of the W3Schools Tryit Editor, click Run to execute the script.
  4. Now, the SMS OTP service starts an authentication flow inside the rendered iframe.
  5. Follow the steps to complete the authentication flow by providing an phone number and entering the received OTP code.

Once the authentication completes successfully, the iframe will redirect the end-user to the returnUrl value you provided when creating the session.

Test authentication with SMS OTP in iframe

Test authentication with SMS OTP in iframe

Third-party cookies

Note that it is important that the end-user's browser has third-party cookies enabled for the authentication flow to work. Learn more about cookies and browser compatibility in the Browser requirements section.

User journey​

The user journey inside the iframe looks like this:

Step 3. Receive the sessionNonce​

Upon successful authentication, the iframe content is redirected to the returnUrl that now contains the sessionNonce as a query parameter.

To obtain the authentication result, you need to extract the sessionNonce query parameter from the redirectUrl. Once you receive the sessionNonce, you may then implement how you want your application to handle the iframe and further redirect the end-user.

Parse the returnUrl​

The return URL follows the https://{returnUrl}/?sessionNonce=<sessionNonce> format. For example, if the returnUrl you sent in your request was https://www.example.com, then you would receive the following request back in the iframe:

Return URL with sessionNonce
https://www.example.com/?sessionNonce=V2G_GwOfuCTNQohLn_MyvJ99mQJT7UKmJ_pmaZdVQg0

Your application needs to extract the sessionNonce from the query parameter of the return URL. Then, you use the sessionNonce to retrieve the session status. When an authentication is successful, the session status response contains the end-user's personal information.

Step 4. Get the session status​

After creating an authentication session with the Signicat Authentication REST API, you can call the Get session status endpoint to retrieve the status of the session, which indicates whether the flow has started, failed or completed.

Request​

To receive the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}?sessionNonce={sessionNonce}.

  • id: The session identifier. You find the session id value in the initial response you received when creating the session.
  • sessionNonce: Note that for an embedded flow you need to provide the extracted sessionNonce value as a query parameter.
  • No data specific to SMS OTP needs to be included in this request.

Example request

Get session status request for embedded flow
curl --location 'https://api.signicat.com/auth/rest/sessions/<sessionId>?sessionNonce=<extracted_session_nonce>' \
--header 'Authorization: Bearer eyJ...'

In the response example above, the session id is 558b1459-335c-4431-8561-b44d9c727bb9 so the request would be:

Example of Get session status request for embedded flow
curl --location 'https://api.signicat.com/auth/rest/sessions/558b1459-335c-4431-8561-b44d9c727bb9?sessionNonce=V2G_GwOfuCTNQohLn_MyvJ99mQJT7UKmJ_pmaZdVQg0' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGc...'
sessionNonce is required

Note that you can only request the status of the session after you have received the sessionNonce as a query parameter to the returnUrl.

Response​

The response you receive from the API contains a status field that informs you about the current status of the authentication session.

Status overview​

The status field returns one of the following values:

Successful authentication​

When the authentication session is successful, you receive a SUCCESS status. Importantly, you receive the personal information of the end-user in the subject field (JSON object) of the response.

For example, the response for a successfully completed session is:

Example of a successful status response for embedded flows
{
    "id": "558b1459-335c-4431-8561-b44d9c727bb9",
    "accountId": "a-sdge-...",
    "authenticationUrl": "https://api.signicat.com/idps/otp/sms?lang=en&transactionId=da4a08f6-3fd8-bb4d-bc5a-7ea11ee80176&messageId=a75d711f-9774-4e69-90d5-2531ed720d41",
    "status": "SUCCESS",
    "provider": "otp-sms",
    "subject": {
        "id": "TOuh-Q-Qx2-XXXXXXXX",
        "idpId": "447700900000",
        "phoneNumber": "447700900000"
    },
    "loa": "low",
    "allowedProviders": [
        "otp-sms"
    ],
    "language": "en",
    "flow": "embedded",
    "requestedAttributes": [
        "phoneNumber",
        "idpId"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-03-25T14:17:21.5008041+00:00"
}

Note that the subject object contains the personal information of the end-user. The values you receive match the attributes that your requested when you first created the authentication session.

Learn more about the different attributes you can specify in your request to SMS OTP in the Attributes reference documentation.

Success

You have now completed the embedded flow with SMS OTP using the Signicat Authentication REST API.

Handling the authentication response​

Upon receiving the end-user's personal information, your application's backend is ready to identify the end-user. How you do this depends on your use case for digital identity.

Once you have processed the personal information of the user and achieved your identity verification goal, you are ready to instruct your application's frontend to continue to the next screen, depending on your application's logic and design.

Browser requirements​

To ensure a successful implementation of the embedded flow in your application, we recommend you consider the following browser requirements.

To maintain a consistent user session across the authentication steps within the iframe, we set a session cookie. However, because the iframe loads content from a different domain than your application, this cookie is treated as a cross-site, or third-party, cookie.

This presents two significant challenges that your integration needs to address.

  1. Cross-Site Request Forgery (CSRF) risk: To function in a cross-site context, we must set the SameSite attribute of the session cookie to None. While this enables the embedded flow, it also removes the browser's default CSRF protections, creating a potential security vulnerability that you need to mitigate.
  2. Third-party cookie blocking: Modern browsers are phasing out support for third-party cookies to address privacy concerns and prevent ad-tracking. When a browser blocks third-party cookies, the embedded session is interrupted and the user cannot proceed with the authentication flow.

To solve both of these challenges simultaneously, Signicat's embedded flow implements Cookies Having Independent Partitioned State (CHIPS), as explained below.

CHIPS​

CHIPS is a modern browser standard that allows a third-party service (like Signicat) to set a cookie that is "partitioned" by the top-level domain (your application). With CHIPS, the browser securely binds the "partitioned" cookie to the top-level domain (your application) active at the exact moment the cookie was issued. This effectively isolates the cookie, preventing its misuse in other contexts.

CHIPS solves both challenges: it mitigates third-party cookie blocking and prevents login CSRF attacks.

There is no additional implementation required on your part to enable CHIPS; it is handled automatically by Signicat's authentication service and supported by modern browsers.

Browser compatibility and monitoring​

Because CHIPS is a relatively new web standard, it requires users to have an up-to-date browser. As of 2025, CHIPS is supported by all major browsers, except for Android WebView.

Browser compatibility

For information about supported browsers, visit the CHIPS Browser compatibility page.

Note that a bug in Safari resulted in CHIPS support being temporarily disabled in Safari between March 2025 and December 2025.

If your end-users encounter frequent errors due to third-party cookie limitations, we recommend you adopt alternative session-handling workarounds until CHIPS-compatible browsers gain broader adoption. Alternative workarounds include embedding a custom session token in the page and manually appending it to HTTP request headers or POST bodies.

If you require assistance, you can contact us by creating a support ticket in the Signicat Dashboard.

Security considerations​

To protect your implementation from fraudulent attacks, make sure you adhere to the Security measures.

Advanced configuration​

Theming​

The pages of the embedded flow render with the default Signicat theme. Support for custom theming of the embedded pages is planned for a future release.

To stay up to date with upcoming feature releases, you can contact us by creating a support ticket in the Signicat Dashboard.

Set the UI language​

To change the language on the SMS OTP UI, use the language parameter in the payload of your request to the Create a new session endpoint. For example, use "language": "el" to set the SMS OTP UI to Greek.

Default language

By default, the UI language is English.

For an overview of the languages supported, see the UI language page.

Prefill user information​

When using the Signicat REST API, you pass user data in the prefilledInput field in the payload of the request to the Create a new session endpoint, so that the end-user does not have to enter their phone number manually when authenticating. For example, this applies to cases when you already know the phone number.

To specify a phone number in the authentication URL, the payload of the request might looks like this:

...
"prefilledInput": {
	"mobile": "+447700900000",
},
...

This will display the phone number to the end-user when they start the authentication flow. To learn more about data prefilling, see the Prefilling user information conceptual guide.

Verify the phone number

For security reasons, we recommend you verify that the phone number you receive in the response from SMS OTP matches the phone number you prefilled in the authentication URL.

Attributes​

For an overview of the attributes available for SMS OTP, see the Attributes reference.

Next steps​

Learn more about Signicat Authentication REST API flows and endpoints in the Authentication REST API documentation.

On this page