Developer Pages

# Integration with Authentication REST API

This page details how to set up an integration with itsme® using the Signicat Authentication REST API with redirect flow.

The Signicat Authentication REST API relies on the OAuth 2.0 protocol for authorisation. OAuth 2.0 is an open protocol to allow secure authorisation in a standardised manner. Requests are sent from your backend server to Signicat's Authentication REST API.

If you want to find out more about the Signicat Authentication REST API, see:

Page contents

# API configuration

To connect to Signicat APIs, you need an API client which consists of a client_id/client_secret pair associated with either your organisation or one of your accounts.

In a typical flow, you pass the client credentials in the API request to obtain an access token. Then, you include the access token as an HTTP Bearer authentication header when sending requests to the Signicat Authentication REST API.

# API client credentials

You create API client credentials in the Signicat Dashboard. To do this follow the steps to Set up an API client in the Accessing Signicat API products guide.

To connect to the Authentication REST API, make sure you use the following settings in your API client:

  • signicat-api in the Allowed scopes.
  • Authentication REST API in the Permissions tab of your API client.
  • A client secret associated with the API client.

# Obtain an access token

Before you continue with the steps in this guide, make sure you obtain an access token as explained in the Obtaining an access token section of the Accessing Signicat API products guide.

# 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®.

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

Field Required Example value Description
allowedProviders No ["itsme"] Specify ["itsme"] to show end-users only itsme®. Don’t send this field if you want to display a list of all the ID methods enabled in your account.
flow Yes redirect MUST have the value redirect.
requestedAttributes Yes ["name", "firstName", "lastName", "dateOfBirth", "nin"] The attributes you wish to get back from the authentication of the end-user.

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

# itsme® services

itsme® offers different scenarios 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 (opens new window).

When you integrate, you control which service to trigger by using attributes. You can learn more about the scopes for each service in the Attributes reference documentation.

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.

# Response

After you create a session, you receive a response with a summary of your request, a unique ID for the process and an authenticationUrl.

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
}

# Use the response

Now, your application can redirect the end-user to the authenticationUrl you obtained in the response. This is a unique URL that allows the end-user to perform the itsme® authentication in the context of the session you just created.

# User journey

At the authentication URL, end-users follow 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 to track whether the flow has started, failed or completed. Responses from successful authentications contain the end-user personal data.

# Request

To get 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 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 response contains a status field, which you can use to monitor the current status of the session. For example, the response for a successfully completed session 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",
    ...
}
# Status overview

The status field could contain one of the following values:

Status Description
WAITING_FOR_USER The end-user has not started to authenticate yet.
SUCCESS The authentication was successful. Authentication result is present in the response.
ABORT The end-user aborted the session.
ERROR The itsme® session was not completed in time.

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

# Use the response

If the returned status is SUCCESS, the JSON object in the subject field of the response contains information about the authenticated end-user. 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.0",
        "userAgent": ""
    },
    "allowedProviders": [
        "itsme"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "dateOfBirth",
        "firstName",
        "lastName",
        "name",
        "nin",
        "idpId"
    ],
    "sessionLifetime": 1200
}

In the response object, you can also see the service provider specified in the provider field. 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
REST
Last updated: 10/04/2024 07:09 UTC

← Attributes reference →