For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Subject-Agnostic Backchannel Authentication (SABA)

Subject-Agnostic Backchannel Authentication (SABA) is a headless flow in the Signicat Authentication REST API. It connects your desktop or mobile app to the itsme® app without user pre-identification.

The SABA flow is most suitable when you want to support:

  • Subject-agnostic login: End-users log in without entering a phone number or national identity number first.
  • Desktop Web2App flows: Desktop web apps start mobile login on the end-user's phone using a dynamic QR code.
  • Simplified mobile App2App flows: Native mobile apps open the itsme® app directly. You do not need to capture redirect callbacks or send token validation requests.
Headless integration options for itsme®

Signicat supports two headless integration patterns for itsme®:

  • Code-based App2App flow (itsme_response_type=code): Uses front-channel app switching and returns an authorisation code to your redirect URL. For details, see the App2App flow guide.
  • Backchannel SABA flow (itsme_response_type=none): Uses server-to-server backchannel calls where Signicat resolves tokens in the background.

We recommend you choose the option that matches your target devices and setup. For a comparison of the two, see the Compare flows table.

How it works​

You can build SABA flows for web and mobile login by using the headless flow of the Signicat Authentication REST API.

In a headless flow, your frontend and backend work separately. You provide your own user interface in your app or website, while your backend talks directly to the Signicat Authentication REST API.

When your backend creates a session with "flow": "headless" and sets "itsme_response_type": "none", Signicat returns an authorizationRequestUrl. Your frontend shows this URL as a deep link button on mobile (App2App) or as a QR code on desktop (Web2App).

Once the end-user opens the link and completes authentication in the itsme® app, Signicat exchanges the token and gets the user claims in the background. Your backend polls the session status endpoint to get the verified identity data of the end-user.

Key features
  • Web2App support: Suitable for desktop web applications. The end-user scans a QR code displayed on screen using their smartphone camera or the itsme® app, approves the request on mobile, and the desktop web page automatically logs in.
  • Full UI control: You keep complete control over the user interface on both desktop and mobile.
  • No manual token exchange: Signicat resolves tokens automatically in the background. Your application does not need to handle an authorisation code or call a token endpoint.
  • Subject-agnostic: End-users start the flow right away without typing a phone number or national ID number.
  • Backend-driven: You request the end-user's attributes (such as name, date of birth or national ID number) in the API payload when you create the session.
  • Polling required: Your backend polls the /sessions/{id} endpoint every few seconds to check when the end-user finishes.

The diagram below shows the interaction between your application, the end-user, the Signicat API and itsme®:

Sequence diagram showing the itsme® SABA backchannel authentication flow

Prerequisites​

  1. Complete the initial setup described in the Set up itsme® guide to configure itsme® in the Signicat Dashboard.

  2. For the complete documentation index, see llms.txt

    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

Configure redirect URLs​

Redirect URLs define where to redirect end-users after they complete authentication in the itsme® app. For mobile apps, these are typically deep links (Universal Links or App Links) back to your app.

To configure redirect URLs:

  1. Log in to the Signicat Dashboard.
  2. Go to Products > eID and Wallet Hub > eIDs.
  3. Select itsme® from the list of eIDs to open the configuration page.
  4. Add a default redirect URL.
  5. Click Save.
Allowed redirect URLs

Only redirect URLs configured for itsme® in the Signicat Dashboard are permitted. When you pass itsme_redirect_url in your session request, it must match one of the URLs configured in the Dashboard. If you omit itsme_redirect_url in the session request, Signicat automatically uses the default redirect URL configured in the Dashboard.

Implement the authentication flow​

In the SABA flow, your application initiates a headless session, presents the returned authorisation link to the end-user and polls Signicat for the session result.

SABA authentication flow

A SABA headless flow consists of three steps:

  1. Create a session: Your backend sends a session request to the Signicat Authentication REST API with "flow": "headless", "itsme_response_type": "none" and client device metadata. Signicat returns an authorizationRequestUrl.
  2. Present the authorisation link: Your application presents the authorizationRequestUrl as an itsme® button on mobile or as a dynamic QR code on desktop. The end-user authenticates in the itsme® app.
  3. Obtain user information: Your backend polls the session status endpoint until the status changes (for example, to SUCCESS) and retrieves the end-user's verified personal information.

Step 1: Create a session​

To initiate an authentication flow, send a POST request from your backend server to the Create a new session endpoint (https://api.signicat.com/auth/rest/sessions).

Request​

POST https://api.signicat.com/auth/rest/sessions HTTP/1.1
Host: api.signicat.com
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json

In the request body, set "flow": "headless" and include "itsme_response_type": "none" in the additionalParameters object.

Mandatory device specification

itsme® requires client device metadata for risk assessment and fraud prevention in SABA requests. Your request must include at least one device specification parameter in additionalParameters (such as ip_address, device_manufacturer, device_model, device_os, device_os_version, device_locale, device_time or referrer_browser_useragent). If no device parameters are provided, the API returns an error.

For example, your request payload can look like this:

{
  "allowedProviders": [
    "itsme"
  ],
  "flow": "headless",
  "additionalParameters": {
    "itsme_response_type": "none",
    "itsme_redirect_url": "https://{app-domain}/path",
    "ip_address": "198.51.100.24",
    "device_manufacturer": "Apple",
    "device_model": "iPhone15,2",
    "device_os": "iOS",
    "device_os_version": "17.4",
    "device_locale": "nl-BE",
    "device_time": "2026-09-07T10:15:00Z",
    "referrer_browser_useragent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Mobile/15E148 Safari/604.1"
  },
  "requestedAttributes": [
    "name",
    "firstName",
    "lastName",
    "dateOfBirth",
    "nin"
  ]
}

Consider the following fields in the request body:

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

Device specification parameters​

You can include the following parameters inside additionalParameters to describe the end-user's device context:

itsme® services​

itsme® organises identity flows into separate services based on your use case. Signicat supports the following itsme® services:

  • Authentication: Authenticate returning users and log them in to your application.
  • Identification: Identify and onboard new users with verified personal data.
  • Qualified signature: Sign electronic documents (available on request; contact us for details).
How to specify a service

The attributes you include in requestedAttributes determine which itsme® service is started for the session. Learn more about which attributes trigger each service on the Attributes reference page.

Response​

A successful request returns an HTTP 201 Created response containing:

  • Metadata about your request.
  • A unique session id to track the authentication process.
  • The idpData object containing the authorizationRequestUrl and transactionId.

Here is an example response:

{
  "id": "db415388-c978-4027-84a6-021bd743ef0b",
  "accountId": "<ACCOUNT_ID>",
  "status": "CREATED",
  "idpData": {
    "authorizationRequestUrl": "https://idp.prd.itsme.services/v2/authorization?request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A...",
    "transactionId": "8aa41ada-3cd0-874b-9acd-bd0a5f7e033f"
  },
  "allowedProviders": [
    "itsme"
  ],
  "flow": "headless",
  "requestedAttributes": [
    "dateOfBirth",
    "firstName",
    "lastName",
    "name",
    "nin"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-10-09T16:30:00.000Z"
}

Consider the following properties inside the idpData object:

  • authorizationRequestUrl: The URL used to start authentication in the itsme® app. Present this URL as a deep link on mobile devices or as a QR code on desktop browsers.
  • transactionId: The unique identifier of the authentication transaction with itsme®.
No tokenRequestUrl in SABA

In the SABA flow, idpData does not contain a tokenRequestUrl. Because Signicat completes token retrieval and verification automatically in the background, your application does not need to send a token validation request.

To direct the end-user to the itsme® authentication session, you need to present the authorizationRequestUrl in your user interface according to the end-user's device. If you display an itsme® button in your application, you need to make sure your application follows the official itsme® button design guide.

Mobile applications (App2App)​

On mobile devices, open the authorizationRequestUrl directly:

  1. Display an itsme® button in your mobile application.
  2. When the end-user selects the button, open the authorizationRequestUrl.
  3. The mobile operating system opens the native itsme® app using a universal link (iOS) or app link (Android).
  4. The end-user confirms their identity in the itsme® app using their PIN or biometrics.
What if the itsme® app is not installed on the user's device?

itsme® implements authorisation request URLs as universal links:

  • If the itsme® app is installed on the device, the native app opens directly.
  • If the itsme® app is not installed, the link opens in the device's web browser and displays the itsme® authentication page.

Desktop web applications (Web2App)​

When your application runs in a desktop browser:

  1. Render the authorizationRequestUrl as a dynamic QR code on your login screen.
  2. The end-user scans the QR code using their smartphone camera or the built-in scanner in the itsme® app.
  3. The itsme® app opens on the end-user's mobile device and displays the authentication request.
  4. The end-user approves the request in the itsme® app while your desktop web page waits and polls the session status.

At the end of the process, the end-user's identity is securely verified within the itsme® ecosystem. Then, the end-user is automatically redirected to the return URL, according to the outcome of the authentication.

You can preview what the authentication flow with itsme® looks like in the About itsme page.

Step 3: Poll session status and obtain user information​

While the end-user completes authentication in the itsme® app, you need to poll the Get session status endpoint from your backend every 1 to 3 seconds to monitor the session status.

Request​

To poll the session status, you need to send a GET request to the Get session status endpoint of the Signicat Authentication REST API at https://api.signicat.com/auth/rest/sessions/{id} using the session id returned in Step 1:

GET https://api.signicat.com/auth/rest/sessions/db415388-c978-4027-84a6-021bd743ef0b HTTP/1.1
Host: api.signicat.com
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Session statuses​

The status field returns one of the following values:

Only successful authentications (SUCCESS) return the personal data of the end-user.

Response​

Once the end-user completes authentication in the itsme® app, the session status changes to SUCCESS. You can find the verified personal information of the end-user in the subject object of the response:

{
  "id": "db415388-c978-4027-84a6-021bd743ef0b",
  "accountId": "<ACCOUNT_ID>",
  "status": "SUCCESS",
  "provider": "itsme",
  "subject": {
    "id": "tXOq9614vLHkXBkENWcZGQO02Fc98IPaHq6iRwK-ytA=",
    "idpId": "rpx5rrbsn4ktvhm3m0q4uh2iepsdat34i9vf",
    "name": "Maxence Legrand",
    "firstName": "Maxence",
    "lastName": "Legrand",
    "dateOfBirth": "1981-04-24",
    "nin": {
      "value": "81042419835",
      "issuingCountry": "BE",
      "type": "PERSON"
    }
  },
  "environment": {
    "ipAddress": "198.51.100.24",
    "userAgent": "Mozilla/5.0..."
  },
  "idpData": {
    "authorizationRequestUrl": "https://idp.prd.itsme.services/v2/authorization?request_uri=urn%3Aietf%3Aparams%3Aoauth%3Arequest_uri%3A...",
    "transactionId": "8aa41ada-3cd0-874b-9acd-bd0a5f7e033f"
  },
  "allowedProviders": [
    "itsme"
  ],
  "loa": "high",
  "flow": "headless",
  "requestedAttributes": [
    "dateOfBirth",
    "firstName",
    "lastName",
    "name",
    "nin"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-10-09T16:30:00.000Z"
}
Success

You have now completed the backchannel SABA authentication flow with itsme®.

Handle the authentication response​

Once your backend receives the subject object, you can match the end-user to an existing account using subject.id or onboard a new user with the verified attributes. Learn more about the returned attributes on the Attributes reference page.

Error handling and session cancellation​

Session expiration​

If the session lifetime expires before the user completes authentication, the status transitions to EXPIRED. To re-attempt authentication, you need to initiate a new session.

Cancel a session (optional)​

You can stop an ongoing authentication session programmatically by calling the Cancel flow endpoint.

This is useful if you want to:

  • Provide a button or link in your UI that lets end-users cancel the transaction.
  • Cancel an active transaction before starting a new session for the same user.

Request​

POST https://api.signicat.com/auth/rest/sessions/{id}/cancel HTTP/1.1
Host: api.signicat.com
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Response​

A successful cancellation returns an HTTP 200 OK response with "status": "CANCELLED":

{
  "id": "db415388-c978-4027-84a6-021bd743ef0b",
  "accountId": "<ACCOUNT_ID>",
  "status": "CANCELLED",
  "provider": "itsme",
  ...
}

Next steps​

Continue your journey with more itsme® guides:

Attributes reference
Attributes reference and data for itsme®
Go to production
Connect to itsme® in a production account

Dive deeper into the Signicat Authentication REST API:

Authentication REST API documentation
Find out more about the Signicat Authentication REST API.
Authentication REST API reference
Discover the endpoints of the Authentication REST API
On this page