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

Headless flow

In a headless flow, your application maintains complete control over the user interface and user experience. Instead of redirecting the end-user to a Signicat-hosted webpage, your application embeds the authentication interaction directly into your web, desktop or native mobile app.

General implementation guide

You can use this guide as a foundation to understand how a headless authentication flow works with our Authentication REST API.

Note that it is important that you check the individual eIDs documentation to learn about the unique features and specific parameters supported by the eID provider of your choice.

Flow overview​

A typical headless flow consists of four main steps:

  1. Create a headless session: Your backend sends a request to the Authentication REST API specifying headless as the flow type.
  2. Present the interaction: Your application renders the authentication challenge (such as a QR code, an app-switching deep link or a challenge code) to the end-user.
  3. Poll for status: Your application periodically queries the session endpoint of the Authentication REST API to monitor the end-user's progress.
  4. Retrieve session details: Once authentication succeeds, your backend collects the verified identity attributes and subject identifier.
Headless flow sequence diagram

Sequence diagram showing the headless flow for Signicat Authentication REST API

Prerequisites​

Before you implement the headless flow, complete the following prerequisites:

  1. Add and configure at least one eID provider in the Signicat Dashboard under Products > eID and Wallet Hub > eIDs. Learn more in the Add eIDs guide.
  2. Verify that your chosen eID provider supports headless authentication. For provider capabilities, see the eIDs documentation.

  3. 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

Step 1: Create a headless session​

To start the authentication process, you need to create a headless session using the Authentication REST API. To do this, send a POST request from your backend server to https://api.signicat.com/auth/rest/sessions ensuring to specify headless as the flow type.

Request​

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

{
  "flow": "headless",
  "callbackUrls": {
    "success": "https://example.com/auth/callback/success",
    "abort": "https://example.com/auth/callback/abort",
    "error": "https://example.com/auth/callback/error"
  },
  "allowedProviders": [
    "<EID_PROVIDER>"
  ],
  "additionalParameters": {...},
  "requestedAttributes": [
    "firstName",
    "lastName",
    "nin",
    "dateOfBirth"
  ]
}

To learn more about the properties of the request payload, see the Create a session endpoint description.

Key parameters​

  • flow: Specifies the flow type. You must set this to headless.
  • allowedProviders: A list containing the specific eID provider identifier. Headless sessions require an explicit provider because your application renders the UI rather than presenting a Signicat provider selection screen.
  • additionalParameters: eID-specific parameters to trigger a supported type of headless flow.
  • requestedAttributes: A list of identity attributes you want Signicat to retrieve from the eID provider. Attribute codes and data availability varies depending on the eID provider(s) you provide in allowedProviders.
Provider-specific parameters

Request parameters and supported attributes vary depending on the eID provider you use in your application. To find out which parameters and configuration options apply to an eID, see the individual eIDs documentation.

Response​

After you create a session, you receive a response containing the following fields:

  • Metadata about your request
  • id: The unique identifier for the session
  • idpData: An object with the details to display the interaction to your end-users

Response example

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "CREATED",
  "flow": "headless",
  "allowedProviders": [
    "<EID_PROVIDER>"
  ],
  "idpData": { "field": "Interaction information" },
  "requestedAttributes": [
    "firstName",
    "lastName",
    "name",
    "nin"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-10-11T07:56:36.587157+00:00"
}

The idpData object contains the interaction details for you to present the authentication interaction to the end-user in your own custom user interface. The data in the idpData varies depending on which eID provider you use and how you present the interaction to your end-users.

Step 2: Present the interaction​

Use the interaction payload returned in the session creation response to render the interface appropriate for the end-user's device. This depends on the format of your interaction payload and could be of the following types:

  • Same-device (mobile app switch): If the end-user authenticates on a mobile device that has the provider app installed, launch the deeplink URL to open the provider's application directly.
  • Cross-device (QR code): If the end-user authenticates on a desktop browser, display the QR code on the screen so they can scan it using their mobile eID app.
  • Manual entry: If the provider requires an identification number (such as a personal number or phone number) before launching the interaction, collect this in your custom form and pass it during session creation.

Step 3: Monitor session status​

Because the end-user completes authentication outside your website or application, your backend must track the session status. To do this, you need to query the Get session status endpoint periodically at regular intervals.

Recommended polling interval

We recommend polling the session endpoint every 2 to 3 seconds. To prevent rate limiting, do not poll more frequently than once per second.

Request​

To retrieve the status of an ongoing session, you need to send a GET request to https://api.signicat.com/auth/rest/sessions/{id}. You can obtain the id value from the response you received upon creating the session.

In the response example above, the id is f47ac10b-58cc-4372-a567-0e02b2c3d479 so the request would be:

GET https://api.signicat.com/auth/rest/sessions/f47ac10b-58cc-4372-a567-0e02b2c3d479 HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

For more information about the request, see the Get session status endpoint description.

Response while in progress​

While the end-user confirms their identity, the endpoint returns a WAITING_FOR_USER status:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "WAITING_FOR_USER"
}

Continue polling until the session status transitions to a terminal state (SUCCESS, ABORTED, ERROR, EXPIRED or CANCELLED).

Status overview​

The status field could contain one of the following values:

Step 4: Retrieve session details​

Optional additional Steps

Note that some eIDs may involve additional steps to complete the authentication process.

Once the session is complete and the end-user has authenticated successfully, the Get session status endpoint returns a SUCCESS status and includes the verified subject identifier and identity attributes:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "accountId": "<YOUR_ACCOUNT_ID>",
  "status": "SUCCESS",
  "provider": "<EID_PROVIDER>",
  "subject": {
    "id": "9578-6000-4-48855",
    "idpId": "9578-6000-4-48855",
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "2002-06-01",
    "nin": {
        "value": "string",
        "issuingCountry": "string",
        "type": "string"
    },
  },
  "environment": {
    "ipAddress": "127.0.0.1",
    "userAgent": "user_agent_test"
  },
  "flow": "headless"
}

Upon receiving a SUCCESS status, you should process and validate the end-user's data according to your use case to log the end-user into your application.

Additional provider steps

Depending on the eID provider and security guidelines, you may need to carry out additional steps to complete the authentication journey. For example, some providers require you to render dynamic, auto-refreshing QR codes, display specific security prompts or show post-authentication confirmation details to the end-user.

To verify whether your chosen method requires extra interaction or display steps, consult the individual eIDs documentation.

Success!

You have now completed a headless flow using the Signicat Authentication REST API.

Next steps​

Explore more topics to build your integration with the eID and Wallet Hub:

eIDs
Find out more about the eIDs
Concepts
Learn about eID and Wallet Hub concepts
Authentication REST API reference
Discover the endpoints of the Authentication REST API
On this page