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

Get started with the integration

Have you tried it out in sandbox first?

We recommend that you create a sandbox account to test our services before implementing them in production.

Prerequisites​

Access to Mobiil-ID​

Before you can create a production account, you need to configure Mobiil-ID access with an onboarding manager. To get help with this, please contact us.

Define the service provider name​

For the complete documentation index, see llms.txt

When enabling access, your onboarding manager will ask you what service provider name you prefer to be displayed for your end-users in the login screens. Signicat will send this to SK ID solutions and let you know when this name is approved. This name will be the same for both Smart-ID and Mobiil-ID.

Certificate information

There are no certificate exchanges needed to use Mobiil-ID.

Create a production account​

Once you have received the needed permissions, you can create the account from the Dashboard:

For the complete documentation index, see llms.txt

  1. Go to Signicat Dashboard > Organisation.
  2. Click the + Add account button.
  3. Under Account Name, enter the name of your account.
  4. Tick the Production account box.
  5. Click the Create button to create the new account.

Add eID to the Dashboard​

For the complete documentation index, see llms.txt

  1. In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > eIDs.
  2. Click + Add new in the top right.
  3. Choose the eID from the list. Then, fill in any required configuration and click Add.
  4. Now, review that the eID is available and displayed as Enabled in the eIDs page.

Set up a connection with a protocol​

To establish a connection between Signicat Mobiil-ID and your application, you need to use a standard authentication protocol.

For the complete documentation index, see llms.txt

Supported authentication protocols

Signicat supports the standard OpenID Connect (OIDC) and SAML 2.0 protocols. In addition, we offer our bespoke Signicat Authentication REST API.

The protocol you choose depends on your goals and preferences. The Authentication REST API provides flexibility and an easy setup. Otherwise, we recommend OIDC, since SAML 2.0 is much more complex to implement and usually requires a federation agent. OIDC is an industry standard with managed user sessions, unlike the Authentication REST API.

To learn more about these authentication protocols, see the Signicat eID and Wallet Hub documentation.

Choose your integration flow​

You can choose between the following integration flows and authentication protocols for Mobiil-ID:

For the complete documentation index, see llms.txt

Redirect flow​

With the redirect flow, you simply initiate a session using one of the supported protocols, and redirect the end-user to the provided redirect URL/URI.

For step-by-step instructions per authentication protocol, see the eID and Wallet Hub Quick start guide > Build a connection.

For information about how to set up the redirect flow with the Signicat Authentication REST API, see the Redirect flow guide.

Headless flow​

If you want 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.

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 initialise a headless authentication with Mobiil-ID, send a POST request to the /sessions endpoint.

Request example

{
  "allowedProviders": ["sk-mobileid"],
  "flow": "headless",
  "requestedAttributes": [
    "name",
    "firstName",
    "lastName",
    "dateOfBirth",
    "nin",
    "age"
  ],
  "prefilledInput": {
    "mobile": "+37251234567",
    "nin": "49002171234"
  },
  "additionalParameters": {
    "message": "This is a message."
  }
}

Key parameters​

For more detailed field descriptions, see the API reference.

prefilledInput​

Mobile phone number is required

To deliver the authentication prompt to the end-user's SIM card, you must provide the following fields:

  • mobile: The end-user's mobile phone number (in E.164 format) in the prefilledInput object
  • nin: The end-user's national identity number in the prefilledInput object

Here is an example of a prefilledInput object:

{
  "prefilledInput": {
    "mobile": "+37251234567",
    "nin": "49002171234"
  }
}

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

requestedAttributes​

You can request the following user information in the requestedAttributes object:

For the complete documentation index, see llms.txt

Response​

When you create the session, Signicat returns an idpData object containing a controlCode:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "accountId": "<YOUR_ACCOUNT_ID>",
  "status": "CREATED",
  "idpData": {
    "controlCode": "2948"
  },
  "allowedProviders": [
    "sk-mobileid"
  ],
  "flow": "headless",
  "requestedAttributes": [
    "name",
    "firstName",
    "lastName",
    "dateOfBirth",
    "nin",
    "age"
  ],
  "sessionLifetime": 1200,
  "expiresAt": "2026-10-11T07:56:36.587157+00:00"
}
Display the control code

Your application must display the 4-digit controlCode (for example, 2948) to the end-user. The end-user receives a prompt on their mobile phone and must confirm that the verification code on their phone screen matches the one displayed in your application before entering their PIN.

2. Check session status​

While the end-user verifies the control code and enters their PIN on their mobile device, poll the session status endpoint periodically.

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

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

Response while pending​

While the authentication prompt is active on the end-user's phone, the endpoint returns a PENDING status:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "status": "PENDING"
}

Response on success​

Once the end-user confirms the transaction on their device, the status transitions to SUCCESS and includes the verified subject details and identity attributes:

{
  "id": "c1f7b9a2-4a5c-4f8e-9d21-a3597b6f2814",
  "accountId": "<YOUR_ACCOUNT_ID>",
  "status": "SUCCESS",
  "provider": "sk-mobileid",
  "subject": {
    "id": "49002171234",
    "name": "Laura Jansons",
    "firstName": "Laura",
    "lastName": "Jansons",
    "dateOfBirth": "1990-02-17",
    "nin": {
      "value": "49002171234",
      "issuingCountry": "EE",
      "type": "CIVIL"
    },
    "age": "36"
  },
  "environment": {
    "ipAddress": "192.0.2.1",
    "userAgent": "Mozilla/5.0..."
  },
  "loa": "high",
  "allowedProviders": [
    "sk-mobileid"
  ],
  "flow": "headless"
}

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