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.
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]
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:
https://api.cmdisp.com/itsme/v1/
https://api.sandbox.cmdisp.com/itsme/v1/
Create an itsme transaction to register or login.
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"
}
token
(required): a unique and secret token to identify the customer, do not share this key and keep it safeservice
(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 birthemail
: requests the email addressphone
: requests the phone numberaddress
: requests the street, postal code, city and country codelocale
(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 itsmephoneNumber
(optional): the phone number of the user in E.164 format; it will be prefilled on the itsme authentication page when provided{
"transactionToken": "SMDhN88yYlE3ug2mUzSsma7Vb3GFBXV61tLgJEYVwJVZ9623kECl7A5p4uqIat2W",
"authenticationUrl": "https://merchant.itsme.be/oidc/authorization..."
}
transactionToken
: the token to retrieve the transaction status and user informationauthenticationUrl
: itsme authentication URL, redirect the user to this URL to start the authentication process200
- Transaction created400
- Invalid parameters, check the response body for the error message500
- Error creating the transactionRetrieve the transaction status and user info (if requested).
Path: /status/{transactionToken}
Method: GET
transactionToken
: the token returned from the transaction request{
"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"
}
}
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 transactionsname
: name informationgivenName
: first namefamilyName
: last namefullName
: full name, consisting the first and last namegender
: 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 formatemailAddress
: email addressaddress
: legal addressstreetAddress
: street address, can be multiline (newline separator \n)postalCode
: postal codecity
: city namecountryCode
: two-letter country code (ISO 3166-1 alpha-2)200
- Request successful, check the body for the transaction status500
- Server error