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

For complete control over the user experience, you can use the headless flow in the Signicat Authentication REST API. For a general overview of the headless flow, see the Headless flow guide.

How it works​

In a headless flow, the user interacts with Smart-ID through one of these methods:

  • QR code flow: Scanning a dynamic QR code (cross-device)
  • App2App and Web2App flows: Clicking a link (same-device)
  • Notification flow: Receiving a push notification

You can determine the flow by providing the appropriate parameters in your authentication request. You also need to design your application to handle the respective flow requirements.

Prerequisites​

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

1. Create a new session​

To create a new session and start an authentication flow, send a POST request to the /sessions endpoint.

Here are request examples for each supported authentication type:

{
  "allowedProviders": ["sk-smartid"],
  "flow": "headless",
  "requestedAttributes": [
    "name",
    "firstName",
    "lastName",
    "dateOfBirth",
    "nin",
    "age"
  ],
  "additionalParameters": {
    "authType": "qr"
  }
}
User-initiated flow

In the QR code flow, the end-user initiates authentication:

  1. You create the session and generate a QR code (from the deviceLink you receive in the response).
  2. The end-user opens the Smart-ID app on their mobile device and scans the code.

Because the end-user identifies themselves when scanning the QR code, you do not need to provide prefilledInput (such as nin) in this request.

Key parameters​

To initialise a headless authentication with Smart-ID, you need to specify the following required fields in the initial request:

For more detailed field descriptions, see the API reference.

You can further configure your authentication process by specifying the following parameters:

additionalParameters​

Use additionalParameters to control the headless authentication behaviour:

prefilledInput​

notification requires prefilled nin

When using the notification authentication type, you must provide the nin (national identity number) of the user, otherwise the transaction will fail.

Example with prefilled nin:

"prefilledInput": {
  "nin": "49002171234"
}

For conceptual documentation about prefilling, see the Prefilling user information guide in the eID and Wallet Hub documentation.

requestedAttributes​

You can request user information using the requestedAttributes list:

For the complete documentation index, see llms.txt

Response examples​

Depending on the authType, the API returns different properties in idpData:

For qr, web2app and app2app, the response contains a deviceLink:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "accountId": "a-sdge-...",
  "status": "CREATED",
  "idpData": {
    "deviceLink": "https://test.smartid.com/device-link?deviceLinkType=QR&sessionToken=..."
  },
  "allowedProviders": [
    "sk-smartid"
  ],
  "flow": "headless",
  "requestedAttributes": [
    "dateOfBirth",
    "firstName",
    "lastName",
    "name",
    "nin",
    "age"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-06-29T11:08:34.9495067+00:00"
}

Here is how you can serve the device link to your end-users:

  • qr: Render the deviceLink as a QR code image for the end-user to scan.
  • web2app / app2app: Render a button or link with the deviceLink to trigger the app switch.

For more details on how the dynamic QR code or other device links should be presented in your application frontend, see the Device link and QR presentation section in the Smart-ID documentation.

Response properties​

For the complete documentation index, see llms.txt

Note the following properties in the response object:

  • status: CREATED indicates that the session has been created but the end-user has not started to authenticate yet.
  • idpData: The flow link or code to drive the authentication in your own custom user interface, as shown in the table below:

2. Check session status and obtain data​

For the complete documentation index, see llms.txt

To poll information regarding the status of an ongoing authentication 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. For more information about the request, see the Get session status endpoint description.

Upon successful authentication, you receive a response containing the user information requested when you initiated the authentication session.

Polling intervals
  • For qr: Poll the status endpoint every 2 to 3 seconds. Smart-ID dynamic QR codes require updating the QR code image if updated links are returned.
  • For notification: Poll the status endpoint every 2 to 3 seconds until the session completes.

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 c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814 so the request would be:

GET https://api.signicat.com/auth/rest/sessions/c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814 HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json
Completing Web2App and App2App flows with userChallengeVerifier

When using web2app or app2app, the Smart-ID app redirects back to your callbackUrl with a userChallengeVerifier query parameter, which is Base64URL encoded.

Pass this value as a query parameter in your GET request to the session status endpoint:

GET https://api.signicat.com/auth/rest/sessions/c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814?userChallengeVerifier=<USER_CHALLENGE_VERIFIER> HTTP/1.1
Authorization: Bearer <ACCESS_TOKEN>
Accept: application/json

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

Response​

Once the user completes authentication, the session status transitions to SUCCESS with the requested attributes:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "accountId": "a-sdge-...",
  "status": "SUCCESS",
  "provider": "sk-smartid",
  "subject": {
    "id": "49002171234",
    "name": "LAURA JANSONS",
    "firstName": "LAURA",
    "lastName": "JANSONS",
    "dateOfBirth": "1990-02-17",
    "nin": {
      "value": "49002171234",
      "issuingCountry": "EE",
      "type": "CIVIL"
    },
    "age": "36"
  },
  "loa": "high",
  "allowedProviders": [
    "sk-smartid"
  ],
  "flow": "headless",
  "requestedAttributes": [
    "name",
    "firstName",
    "lastName",
    "dateOfBirth",
    "nin",
    "age"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-07-03T07:19:28.6439001+00:00"
}

Data and attributes​

Attributes in your request allow you to specify the users' personal information you want to obtain from an authentication session. Learn more about the attributes supported by Smart-ID in the Attributes reference page.

Next steps​

Dive deeper into Authentication REST API and improve your application with advanced security features:

Signicat Authentication REST API
Find out more about available flows in the eID and Wallet Hub documentation
Message level encryption (MLE)
Read more about how to set up encryption
API reference
Look up endpoint and parameter details in the reference guide
On this page