App2App flow

App2App is a flow for mobile authentication where you route the end-user directly from your native mobile application to the itsme® app to authenticate, without having to open an in-app browser first.

This is relevant both when you want to provide a seamless user experience and when direct app switching is a requirement.

Note that App2App flows require that you provide your own user interface and that the end-users already have the itsme® app installed on their mobile device.

How it works

You can build App2App flows for mobile authentication by leveraging the headless flow of the Signicat Authentication REST API.

In a headless flow, frontend and backend components are separate and operate independently. This way you maintain complete control over the user experience and app switching during an authentication session.

To perform an authentication, you send requests from your backend server to the Signicat Authentication REST API. On the frontend side, you need to provide your own user interface within your app or website, since there is no Signicat-provided user interface involved.

Key features

No redirect or iframe: Unlike the redirect or iframe flows, the headless flow does not provide a URL for the end-user to navigate to. The itsme® app is automatically opened on the end-user's device.
Full UI control: You have complete control over the user interface.
Backend-driven: You request the end-user's attributes (for example, name or date of birth) in the API request when creating the session, as requestedAttributes.
Polling required: Your app must poll the /sessions/{sessionId} endpoint every few seconds to know when the end-user has completed authentication.
Great for mobile apps: Since no browser is required, it is well-suited for native mobile app experiences.

The diagram below shows how the App2App flow works:

App2App authentication flow with itsme® (Click to expand)

Sequence diagram showing App2App authentication with itsme®

Prerequisites

Follow the steps on the Initial preparations page to establish a connection with itsme®.
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
- Authentication REST API for conceptual documentation.
- API Reference for endpoint descriptions.

Configure redirect URLs

Redirect URLs allow you to define links where to redirect the end-users after they have authenticated with itsme®. These URLs are most likely deep links to pages and content inside your app. This pattern ensures a seamless user experience with app-to-app switching.

Note

It is important that you configure the redirect URLs before you start implementing authentication flows with itsme®, since redirect URLs are added to an allowlist and are validated before authentication.

To configure your app's redirect URLs, do this:

Log in to the Signicat Dashboard.
Navigate to Products > eID and Wallet Hub > eIDs.
Select itsme® from the list of eIDs to open the configuration page.
Add a default redirect URL. Make sure to follow the format requirements explained below.
Redirect URL format
- The redirect URI MUST match the value you pass as a parameter in the additionalParameters in the authorisation request.
- The redirect URI MUST begin with the scheme https.
- The redirect URI SHALL NOT be a custom URL.
- The fragment identifier introduced by a hash mark # SHALL NOT be used.
- The redirect URI is case-sensitive. Its case MUST match the case of the URL path of your running application.
- For mobile apps, make sure that your redirect URIs are configured as Universal Link (iOS) and App Link (Android). This allows your application to be opened directly without first launching a web browser.
Optional. Add multiple redirect URLs.
Click Save to save the configuration.

Redirect URLs allowlist

Only the redirect URLs configured in the Signicat Dashboard are allowed in your authorisation request. If you don't specify any redirect URL in your authorisation request, the default redirect URL is used.

Implement the authentication flow

In an authentication flow, your application redirects your end-user to the itsme® app for secure authentication and receives the end-user's personal information that you can later process further.

App2App authentication flow - Steps (Click to expand)

App2App authentication flow

An App2App authentication flow consists of the following steps:

Display the itsme® button: The end-users selects the button to start an authentication with itsme®.
Create a session:
1. Send authorisation request: Your application creates an authorisation request and sets the redirect URL to trigger a login redirect.
2. Receive redirect response: Your application receives a redirect response from Signicat's authorisation server, containing a deep link URL to the itsme® app.
User authentication:
1. Redirect to itsme® app: Your application opens the deep link URL, which switches the user to the native itsme® app.
2. User authenticates: The end-user authenticates using the itsme® app on their device.
Obtain user information
1. Parse the code from the redirect URL: The itsme® app returns the end-user to your app's redirect URL. The URL contains an authorisation code and a state.
2. Validate the code with the token endpoint: Your application's backend server sends the authorisation code to the token endpoint for validation.
3. Obtain personal information Your backend requests the session result from the Signicat authorisation server. The response contains the end-user's personal information.

Step 1. Generate itsme button

First, you need to create a button to allow your end-users to authenticate with itsme®. Check the Button design guide before you start the integration.

When the end-user clicks the button in your app to authenticate with itsme®, you app should respond by initiating an authentication flow, as explained next.

Step 2. Create a session

To initiate an authentication flow, you need to send a request to the Signicat Authentication REST API and create a session.

Request

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

For example, your request payload could look like this:

{
    "allowedProviders": [
        "itsme"
    ],
    "flow": "headless",
    "additionalParameters": {
        "itsme_redirect_url": "https://{app-domain}/path",
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ]
}

Consider the following properties in the request body:

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

itsme® services

itsme® organises authentication flows into separate services to verify someone's identity online. A service is a way to restrict personal information (attributes) to the scope of a specific use case for digital identity, like logging in your returning users.

Signicat supports the following itsme® services:

Authentication: Authenticate returning users. Ideal to log in your existing users securely.
Identification: Identify and onboard new users to your services.
Signing: (Available on request) Perform signing of electronic documents. For more information, contact us.

How to specify a service

The attributes you specify with the requestedAttributes in the payload of your request determine which itsme® service to use in a session.

You can learn more about what attributes initiate a specific itsme® service in the Attributes reference documentation.

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 idpData object with deep link URL. You need this to redirect the end-user to itsme® for authentication.

Here is an example response:

{
    "id": "db415388-c978-4027-84a6-021bd743ef0b",
    "accountId": "a-sdge-Adv...",
    "status": "CREATED",
    "idpData": {
        "authorizationRequestUrl": "https://idp.e2e.itsme.services/v2/authorization?ui_locales=en&scope=openid+service%3ASignicat_EXAMPLE_DEV&claims=%7B%22id_token%22%3A%7B%22birthdate%22%3Anull%2C%22http%3A%5C%2F%5C%2Fitsme.services%5C%2Fv2%5C%2Fclaim%5C%2FIDIssuingCountry%22%3Anull%2C%22name%22%3Anull%2C%22http%3A%5C%2F%5C%2Fitsme.services%5C%2Fv2%5C%2Fclaim%5C%2FBENationalNumber%22%3Anull%2C%22given_name%22%3Anull%2C%22family_name%22%3Anull%7D%7D&response_type=code&redirect_uri=https%3A%2F%2Fexample.com&state=HOiwzUyqdM1Pf7ewufjb9570cyW8WbFX1a5orfzz4JA%3Aa-sdge-AMTzsLg5v6Xl6PLSP166&nonce=vh24ghjbv7yU0Nj2MKB6TjupGmoKQOmGAR6ZMh-gHW8&client_id=bswmvR",
        "tokenRequestUrl": "https://api.signicat.com/idps/oidc-vendor/itsme/login-headless/token",
        "transactionId": "8aa41ada-3cd0-874b-9acd-bd0a5f7e033f"
    },
    "allowedProviders": ["itsme"],
    "flow": "headless",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin",
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-03-19T08:36:06.2964843+00:00"
}

Consider the following properties of the idpData object inside the payload of the response:

authorizationRequestUrl: A deep link URL to redirect the end-user to the itsme® app. This is a unique URL that allows the end-user to perform an authentication with itsme® within the context of the session you have just created.
tokenRequestUrl: The Token Request URL. You use this to validate the authorisation code you receive back from the itsme® app after authentication.
transactionId: The unique identifier of the authentication transaction with itsme®.

Step 3: User authentication

In this phase, the end-user is redirected to the itsme® app to authenticate. Upon successful authentication, the itsme® app hands control back to your application, providing a one-time code required for the token validation.

User authentication in itsme

Now, your app needs to use the authorizationRequestUrl to open the itsme® app directly therefore redirecting the end-user to perform an authentication. Once your application opens the authorizationRequestUrl, the end-user mobile seamlessly opens and switches to the itsme® native application.

Then, the end-user must complete the authentication process as prompted by the itsme® app. This typically involves a secure, provider-specific action, such as entering a PIN, or using biometrics.

What if the itsme® app is not installed on users device?

itsme® has implemented request URLs as universal links. This means that:

If the itsme® app is installed on the device, the app opens on the device.
If the itsme® app is not installed on the device, the push request will open itsme® in a browser and display the itsme® authentication page.

User journey

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

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.

Monitor the session status

After creating an authentication session with the Signicat Authentication REST API, you can make calls the Get session status endpoint to monitor the current status of the session and track whether the flow has started, failed or completed. This is useful if you want to poll for information about the session while the authentication is ongoing.

The status field returns one of the following values:

Note that only successful authentications return the personal data of the end-user.

Status request

To receive the status of a session, send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You find the session id value in the initial response you received when creating the session. No data specific to itsme® needs to be included in this request.

In the response example above, the session id is db415388-c978-4027-84a6-021bd743ef0b so the request would be https://api.signicat.com/auth/rest/sessions/db415388-c978-4027-84a6-021bd743ef0b.

Polling

Your app must poll the /sessions/{id} endpoint every few seconds to know when the end-user has completed authentication.

When an authentication is successful, the /sessions/{id} endpoint will return the end-user's personal information.

Redirect back to your app

Upon successful authentication, the itsme® app will immediately redirect the end-user back to your application.

This is achieved by launching the itsme_redirect_url that you included as a parameter in the payload of the initial request to create a session. If you left the field empty in your request, the end-user is redirected to the default redirect URL configured in the Signicat Dashboard.

Note

If your itsme_redirect_url is not configured as a Universal Link (iOS) or an App Link (Android), the operating system will default to opening the URL in a standard web browser. This interrupts the native experience and is not a true App2App flow.

Response data

When redirecting the user back to your application, the itsme® app appends the code and state parameters to your redirect URL. Your application must be able to parse these values from the incoming URL.

Example of redirect response from the itsme® app:

https://yourapp.example.com/callback?code=a1b2c3d4-i3j4k5l6m7n8&state=abc123xyz456

You need these values to validate the authentication flow and obtain the user information.

Step 4. Obtain user information

After the end-user has completed the authentication in the itsme® app and returned to your mobile application, you are ready to validate the flow and retrieve their personal information for further processing.

Validate code and state

With the code and state now captured in your mobile application, you are ready to validate them against the token validation server. You must perform this operation with your backend server for security reasons.

Security considerations

When validating, make sure to follow these guidelines:

Secure handoff: Your mobile app must securely send the received code and state values to your backend server.
Backend token request: You send your token request from your backend server. This is a server-to-server call and must not be made from the client-side mobile app.
State verification: Before making the token request, your backend must validate that the state value received from the mobile app matches the state value originally generated in the authorizationRequestUrl. This is a critical security measure to prevent Cross-Site Request Forgery (CSRF) attacks.

Token validation request

To validate, you need to send a POST request to the tokenRequestUrl. This is the Token Request URL that you received in the initial response when creating a session with the Signicat Authentication REST API. For itsme®, the tokenRequestUrl is https://api.signicat.com/idps/oidc-vendor/itsme/login-headless/token.

Your backend server sends a POST request to the tokenRequestUrl, passing the code, state and transactionId as part of the request body.

POST /idps/oidc-vendor/itsme/login-headless/token HTTP/1.1
Host: api.signicat.com
Content-Type: application/json
Authorization: Bearer API_ACCESS_TOKEN
Signicat-AccountId: a-sdge-AMTzsLg...P166
Content-Length: 223

{
    "code": "8j988u5q8q1779c00y7hi9qg7aeyz4dcs447",
    "state": "X4w83EqXar8n0XhP2qbldIP7XpHKqT-OVPd5sK5K33w%3Aa-sdge-AMTzsLg...P166",
    "transactionId": "5da292ab-6bbc-a84f-8425-7f167d77147f"
}

Consider these properties:

transactionId: The transaction ID from the initial request to create the session.
state: The state value returned by the itsme® app as a parameter in the return URL.
code: The authorisation code returned by the itsme® app as a parameter in the return URL.

Upon validation of the code, the Signicat API will respond in one of the following ways:

After successfully validating the authorisation code, you are ready to complete the authentication flow.

Obtain user data

After validating the authentication session, you are ready to retrieve the end-user's personal information. To do this, you need to make a call to the Get session status endpoint of the Signicat Authentication REST API, as explained in the Status request section.

If you are polling the endpoint (every 1 to 3 seconds), wait until the status value is either SUCCESS, ABORT, or ERROR, at which point the session is finalised.

Response

When the authentication session is successful, the Get session status endpoint returns a SUCCESS status. Now, you find the personal information of the end-user in the subject field (JSON object) of the response. For example:

{
    "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": "192.0.2.2",
        "userAgent": ""
    },
    "idpData": {
        "authorizationRequestUrl": "https://idp.e2e.itsme.services/v2/authorization?ui_locales=en&scope=openid+service%3ASignicat_EXAMPLE_DEV&claims=%7B%22id_token%22%3A%7B%22birthdate%22%3Anull%2C%22http%3A%5C%2F%5C%2Fitsme.services%5C%2Fv2%5C%2Fclaim%5C%2FIDIssuingCountry%22%3Anull%2C%22name%22%3Anull%2C%22http%3A%5C%2F%5C%2Fitsme.services%5C%2Fv2%5C%2Fclaim%5C%2FBENationalNumber%22%3Anull%2C%22given_name%22%3Anull%2C%22family_name%22%3Anull%7D%7D&response_type=code&redirect_uri=https%3A%2F%2Fexample.com&state=HOiwzUyqdM1Pf7ewufjb9570cyW8WbFX1a5orfzz4JA%3Aa-sdge-AMTzsLg5v6Xl6PLSP166&nonce=vh24ghjbv7yU0Nj2MKB6TjupGmoKQOmGAR6ZMh-gHW8&client_id=bswmvR",
        "tokenRequestUrl": "https://api.signicat.com/idps/oidc-vendor/itsme/login-headless/token",
        "transactionId": "8aa41ada-3cd0-874b-9acd-bd0a5f7e033f"
    },
    "allowedProviders": [
        "itsme"
    ],
    "loa": "high",
    "flow": "headless",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin",
        "idpId"
    ],
    "sessionLifetime": 1200,
    "expiresAt": "2026-03-19T16:23:40.999662+00:00"
}

Success

You have now completed the App2App identity verification flow with itsme®.

Handling the authentication response

Upon receiving the end-user's personal information, your application's backend can identify the end-user, either by linking them to an existing account or provisioning a new one. This depends on the itsme® service you integrate with and your use case for digital identity.

The attributes you request in your flows determine the itsme® service you integrate with. Learn more in the Attributes reference documentation.

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

How it works​

Prerequisites​

Configure redirect URLs​

Implement the authentication flow​

Step 1. Generate itsme button​

Step 2. Create a session​

Request​

itsme® services​

Response​

Step 3: User authentication​

User authentication in itsme​

User journey​

Monitor the session status​

Status request​

Redirect back to your app​

Step 4. Obtain user information​

Validate code and state​

Token validation request​

Obtain user data​

Response​

Handling the authentication response​

Next steps​

How it works

Prerequisites

Configure redirect URLs

Implement the authentication flow

Step 1. Generate itsme button

Step 2. Create a session

Request

itsme® services

Response

Step 3: User authentication

User authentication in itsme

User journey

Monitor the session status

Status request

Redirect back to your app

Step 4. Obtain user information

Validate code and state

Token validation request

Obtain user data

Response

Handling the authentication response

Next steps