itsme® provides every Belgian citizen with a unique, secure mobile identity. The itsme app offers everyone with a Belgian eID one online identification method for all digital transactions; from logging in and creating an account to confirming payments online.

In addition to identification, it can also provide information about the name, address, date of birth, gender, locale, phone number and email address of the user, if the user agrees to provide these.

CM provides an easy to use API to integrate itsme into your website.

Getting started

Before starting integration of itsme into your services, we advise you to read our implementation guide. This guide can be used for a step-by-step implementation of itsme. It explains the itsme service in detail, provides a style guide (including logos, colors and buttons) and explains onboarding process and requirements.

Download: implementation guide (PDF)

An up-to-date swagger specification is available.

If you need technical assistance, please contact [email protected]

How to use

1. Create a transaction to register or login, stating which (if any) user information you want
2. Redirect the user to the itsme login page using the returned authentication URL
3. The user enters their phone number (if not provided)
4. The user opens the itsme app, selects the notification and approves or denies the transaction
5. The user is redirected to your website when the transaction has finished
6. Check if the transaction was successful and retrieve the requested user information

If you are curious about how your consumers will experience using itsme, you can experiment with CM's itsme demo.

Base URL of the API:

• Production: https://api.cmdisp.com/itsme/v1/
• Sandbox: https://api.sandbox.cmdisp.com/itsme/v1/

Create an itsme transaction to register or login.

Request:

Path: /transactions
Method: POST
Content-Type: application/json

{
  "token": "00000000-0000-0000-0000-000000000000",
  "service": "register",
  "scopes": ["profile", "email", "phone", "address"],
  "locale": "nl",
  "redirectUrl": "https://example.com",
  "phoneNumber": "+32471234567"
}

Parameters:

• token (required): a unique and secret token to identify the customer, do not share this key and keep it safe
• service (required): the type of the transaction, login or register
• scopes (optional): the information that you want to request from the user, supported values:
  • profile: requests name, gender, locale and date of birth
  • email: requests the email address
  • phone: requests the phone number
  • address: requests the street, postal code, city and country code
• locale (optional): the locale in which to display the itsme UI, supported values: en, nl, fr and de
• redirectUrl (required): the URL the user is redirected to when the transaction is finished and the user leaves itsme
• phoneNumber (optional): the phone number of the user in E.164 format; it will be prefilled on the itsme authentication page when provided

Response:

{
  "transactionToken": "SMDhN88yYlE3ug2mUzSsma7Vb3GFBXV61tLgJEYVwJVZ9623kECl7A5p4uqIat2W",
  "authenticationUrl": "https://merchant.itsme.be/oidc/authorization..."
}

Parameters:

• transactionToken: the token to retrieve the transaction status and user information
• authenticationUrl: itsme authentication URL, redirect the user to this URL to start the authentication process

Response codes:

• 200 - Transaction created
• 400 - Invalid parameters, check the response body for the error message
• 500 - Error creating the transaction

Retrieve the transaction status and user info (if requested).

Request:

Path: /status/{transactionToken}
Method: GET

Parameters:

• transactionToken: the token returned from the transaction request

Response:

{
    "status": "success",
    "userId": "QC1JJ6AgPTnDWTP3p6p3S1kMzPkLCVN41vzfaTxw",
    "name": {
        "givenName": "Lucas",
        "familyName": "Maes",
        "fullName": "Lucas Maes"
    },
    "gender": "male",
    "birthdate": "1974-01-31",
    "locale": "nl",
    "phoneNumber": "+32471234567",
    "emailAddress": "[email protected]",
    "address": {
        "streetAddress": "Rue Neuve 1",
        "postalCode": "1000",
        "city": "Bruxelles",
        "countryCode": "BE"
    }
}

Parameters:

Note: The transaction status is always returned, the user info fields only when the transaction was successful. User information can only be provided once per successful transaction, the provided info depends on the requested scopes.

• status: status of the transaction; open, success, cancelled, failure or expired

• userId: an identifier unique per user, that's consistent across transactions
• name: name information
  • givenName: first name
  • familyName: last name
  • fullName: full name, consisting the first and last name
• gender: gender, male or female
• birthdate: date of birth in ISO 8601 Date format (YYYY-MM-DD)
• locale: locale, either en, nl, fr or de
• phoneNumber: phone number in international E.164 format
• emailAddress: email address
• address: legal address
  • streetAddress: street address, can be multiline (newline separator \n)
  • postalCode: postal code
  • city: city name
  • countryCode: two-letter country code (ISO 3166-1 alpha-2)

Response codes:

• 200 - Request successful, check the body for the transaction status
• 500 - Server error