itsme

The itsme® API is an offering of Rabo Identity Services for businesses that want to identify their users based on itsme.

Itsme is a digital ID, which users can use to identify and authenticate themselves using the Itsme app available on the App Store or Google Play Store, on their mobile devices. Itsme is an initiative of Belgian Mobile ID, a consortium of four major Belgian banks (Belfius, BNP Paribas Fortis, ING, KBC) and Belgian network operators.  itsme® is mainly used in Belgium but also available in the Netherlands.

📘

To use Itsme, the users should be 18 years or older, own a smartphone and a Belgian eID or a Dutch ID with NFC. Itsme can also be used to legally sign documents, this functionality is covered as part of the Sign API available on the Rabobank Developer Portal. 

Using this API, you confirm the identify your customers during the onboarding process, verify the age of a user or perform an 18+ check, receive (validated) personal data, have customers log in, update customer data, and have documents signed online at a qualified level. With itsme, your customers can safely share their data with you and have it prefilled and you can further supplement or update existing customer data to (re)identify your customers due to laws and regulations quickly and easily. This way you can offer your customers convenience and a better online customer experience.

Using the API

After your account set up is complete, subscribe the itsme API to your application.  

With itsme, your users can Log in and Identify themselves. Multiple itsme methods (identification, authentication) can be consumed through one API using the same flow. 

Flow

A user journey for the itsme API is summarized following 5 steps:

1. The user visits your website or app and clicks the itsme button for identification, login.
2. The user enters their telephone number and opens the itsme app. They are automatically redirected to the app on a mobile phone.
3. The user is able to view the requested service permission and the data required. The user approves the request and provides confirmation with a 5-digit PIN code.
4. The user is redirected to your company's website or app.
5. Rabo Identity Services retrieves a confirmation of the successful transaction and sends you the requested data attributes.

Create a session

Start a session to receive an authentication URL to redirect the user with a POST sessions request.

POST https://api.rabobank.nl/openapi/ris/auth/itsme/sessions

To view full list of POST parameters, go to:

• POST/ris/auth/itsme/sessions

The values provided in the requestedAttributes field determine itsme flow should be initiated (Identification or Authentication), more examples below.

POST itsme session

You can start an itsme session by using the POST /sessions request.

Use the following example request body to start an itsme Identification flow:

{
    "callbackUrls": {
        "success": "https://api.rabobank.nl/success",
        "abort": "https://api.rabobank.nl/abort",
        "error": "https://api.rabobank.nl/error"
    },
    "language": "nl",
    "requestedAttributes": [
        "name",
        "firstName",
        "lastName",
        "email",
        "gender",
        "dateOfBirth",
        "phoneNumber",
        "address",
        "nationality",
        "placeOfBirth",
        "countryOfBirth"
    ],
    "externalReference": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "sessionLifetime": 1200
}

This results in the following example response body with status Created:

{
  "id": "472b1cf0-2c2e-1647-9dcc-035f11643943",
  "authenticationUrl": "https://api.rabobank.nl/broker/sp/external-service/login?messageId=68a7d453-39f2-e248-a099-0bf80a496066&transactionId=472b1cf0-2c2e-1647-9dcc-035f11643943",
  "status": "CREATED",
 "callbackUrls": {
        "success": "https://api.rabobank.nl/success&sessionId=472b1cf0-2c2e-1647-9dcc-035f11643943",
        "abort": "https://api.rabobank.nl/abort&sessionId=472b1cf0-2c2e-1647-9dcc-035f11643943",
        "error": "https://api.rabobank.nl/error&sessionId=472b1cf0-2c2e-1647-9dcc-035f11643943"
    },
  "language": "nl",
  "requestedAttributes": [
    "idpId",
    "name",
    "firstName",
    "lastName",
    "email",
    "gender",
    "dateOfBirth",
    "phoneNumber",
    "address",
    "nationality",
    "placeOfBirth",
    "countryOfBirth"
  ],
  "externalReference": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionLifetime": 1200
}

📘

For each session, a unique sessionId is generated to identify the session.

To view the POST parameters, read the endpoint description for POST /ris/auth/itsme/sessions. The full list of available attributes supported through the itsme API are listed in the API specifications.

After the user flow is complete (regardless of the method), the user is redirected back to your own application using the redirect URLs provided in the request body and the status changes to a final state.

This should trigger your application to make a request to the GET endpoint and fetch the final result.

Retrieve a session

When the user is being redirected back to your own application, the session reaches a final state and the result can then be fetched using a GET /session/:sessionId request.

GET iDIN session result

GET https://api.rabobank.nl/openapi/ris/auth/itsme/sessions/472b1cf0-2c2e-1647-9dcc-035f11643943

To view the GET parameters, read the endpoint description for GET /ris/auth/itsme/sessions/:sessionId

{
    "id": "472b1cf0-2c2e-1647-9dcc-035f11643943",
    "authenticationUrl": "https://api.rabobank.nl/broker/sp/external-service/login?messageId=43b6075c-924f-aa4d-98f7-05aba9ff2881&transactionId=472b1cf0-2c2e-1647-9dcc-035f11643943",
    "status": "SUCCESS",
    "provider": "itsme",
    "subject": {
        "id": "Fhrm9HPjvVCpDusj4tQw0c1xofK1jIiZbN9P1VTLCsM=",
        "idpId": "egoee5m0qg6l27plme976y38c89x5ih5rg2p",
        "name": "Robin Loy",
        "firstName": "Robin",
        "lastName": "Loy",
        "gender": "male",
        "dateOfBirth": "1988-12-18",
        "locale": "EN",
        "nin": {
            "value": "88121847346",
            "issuingCountry": "BE",
            "type": "PERSON"
        },
        "phoneNumber": "+32 466549526",
        "address": "Avenue Louise 11 1000 Brussels",
        "addressFormatted": {
          "fullAddress": "Avenue Louise 11 1000 Brüssel",
          "street": "Avenue Louise 11",
          "city": "Brüssel",
          "postalCode": "1000"
        },
        "nationality": "Belgian",
        "placeOfBirth": "Brussels"
    },
    "callbackUrls": {
        "success": "https://api.nl/success&sessionId=472b1cf0-2c2e-1647-9dcc-035f11643943",
        "abort": "https://api.nl/abort&sessionId=472b1cf0-2c2e-1647-9dcc-035f11643943",
        "error": "https://api.nl/error&sessionId=472b1cf0-2c2e-1647-9dcc-035f11643943"
    },
    "allowedProviders": [
        "itsme"
    ],
    "flow": "redirect",
    "requestedAttributes": [
        "idpId",
        "name",
        "firstName",
        "lastName",
        "email",
        "gender",
        "dateOfBirth",
        "phoneNumber",
        "address",
        "nationality",
        "placeOfBirth",
        "countryOfBirth"
    ],
    "sessionLifetime": 1200
}

🚧

• Each response contains a X-Trace-Id header which can be used for troubleshooting failed transactions
• Certain fields may not be available in the response body, this depends on the availability in the source and the type of request. Read the response schema object to understand which fields can be part of the response body.

All responses are signed by Rabobank, to validate the response read Validate signed responses

Subject ID and login

The subject ID (subject.id field in the JSON response) uniquely identifies a given user account. The subject ID does not change over time, even if other user attributes (for example email or phone number) associated with that user account are updated. Your application server should use the subject.id to log in end-users returning to your application.

Test account

In order to complete the itsme flow in the Sandbox and Pre-production environments, it's required to use a test version of the itsme application. A test account and access to the itsme test application can be facilitated by Rabobank, reach out to your implementation manager for an itsme test account.

Other scenarios

The authentication method and age verification method can also be simulated through Sandbox using the test data below: