Skip to main content

Integration with Authentication REST API

This guide shows how to set up an integration with itsme® by using the redirect flow of the Signicat Authentication REST API.

The Signicat Authentication REST API also supports a headless flow, which allows you to set up App2App flows for mobile applications. Learn more about this option in the App2App flows guide.

Prerequisites​

  1. Follow the steps on the Initial preparations page to establish a connection with itsme®.

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

Redirect flow​

This section details how to set up authentication for itsme® using the redirect flow. The redirect flow allows you to pass an authorization URL to your end-users that they can open in a browser to follow an identity verification flow with itsme®.

itsme® services​

itsme® offers separate services to verify a person's digital identity. Signicat supports the following services:

  • Authentication: to authenticate recurring end-users. Use this to log in end-users securely to your application.
  • Identification: to identify, onboard end-users and access their verified data.
  • Signing: for more information, contact us.

When you integrate, the attributes you specify in your request determine which service to use. The requestedAttributes in the payload of your request allow you to control which itsme® service flow to initiate and present to your end-users.

You can learn more about the attributes specific for each service in the Attributes reference documentation.

Create a session​

Request​

To create a session using the Authentication REST API, send a POST request to https://api.signicat.com/auth/rest/sessions.

For example, include the following fields in the payload:

{
    "allowedProviders": [
        "itsme"
    ],
    "flow": "redirect",
    "callbackUrls": {
        "success": "https://example.test/get?status=success",
        "abort": "https://example.test/get?status=abort",
        "error": "https://example.test/get?status=error"
    },
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "dateOfBirth",
        "nin"
    ]
}

Note the following fields in the payload of the request:

For more information about the "Create a session" endpoint, see the API Reference description.

Response​

After you create a session, you receive a response with:

  • The metadata of your request.
  • A unique ID to recognise the process.
  • The authenticationUrl, where you can direct the end-user to authenticate.

Here is an example response:

{
    "id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
    "accountId": "a-sdge-Adv...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=ddee6370-b118-3f45-a34d-8cdaa9e675bc&transactionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
    "status": "CREATED",
    "callbackUrls": {
        "success": "https://example.test/get?status=success&sessionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
        "abort": "https://example.test/get?status=abort&sessionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
        "error": "https://example.test/get?status=error&sessionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56"
    },
    "allowedProviders": [
        "itsme"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin",
        "idpId"
    ],
    "sessionLifetime": 1200
}

Authentication URL​

Now, your application needs to redirect the end-user to the authenticationUrl you received in the response. 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.

User journey​

By navigating to the authentication URL, the end-user starts an authentication flow with itsme®. You can preview what the flow looks like in the About itsme page.

When the end-user completes the authentication flow, they are automatically redirected to the callbackUrls according to the outcome of the authentication.

Get the session status​

During the authentication process, you can monitor the status of the session and track whether the flow has started, failed or completed.

The status field could contain one of the following values:

Note: Only successful authentications return the personal data of the end-user.

For more information about the "Get session status" endpoint, see the API Reference description.

Request​

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

In the response example above, the id is 4ccb8a1b-6f40-e146-af1b-15f1c6eabb56 so the request would be https://api.signicat.com/auth/rest/sessions/4ccb8a1b-6f40-e146-af1b-15f1c6eabb56.

Response​

The status field in the response yields the current status of the session. For example, the response from a successful authentication is:

{
    "id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
    "accountId": "a-sdge-Adv...",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=ddee6370-b118-3...",
    "status": "SUCCESS",
    "provider": "itsme",
    ...
}

Use the response​

When you receive a SUCCESS status, you can find the personal information of the end-user in the subject field (JSON object) of the response. For example:

{
    "id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
    "accountId": "<ACCOUNT_ID>",
    "authenticationUrl": "https://<YOUR_SIGNICAT_DOMAIN>/broker/sp/external-service/login?messageId=ddee6370-b118-3f45-a34d-8cdaa9e675bc&transactionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
    "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"
        }
    },
    "callbackUrls": {
        "success": "https://example.test/get?status=success&sessionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
        "abort": "https://example.test/get?status=abort&sessionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
        "error": "https://example.test/get?status=error&sessionId=4ccb8a1b-6f40-e146-af1b-15f1c6eabb56"
    },
    "environment": {
        "ipAddress": "192.0.2.2",
        "userAgent": ""
    },
    "allowedProviders": [
        "itsme"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin",
        "idpId"
    ],
    "sessionLifetime": 1200
}

The provider field returns the name of the service provider. This can be useful if you specified more than one provider when you created the session.

Success

You have now completed an identity verification flow with itsme® using the Signicat Authentication REST API.

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