Skip to main content

Attributes reference

You use itsme® to verify end-user identity and obtain relevant personal details.

This page shows what end-user information you can retrieve for a given authentication protocol.

Note

Use of the Belgian RRN (national identity number) is subject to specific legislation. For certain uses, you must obtain specific authorisation by FOD/SPF IBZ. For more details, refer to the applicable laws (for example, this one or other updated, applicable laws).

Available attributes

Attributes (scopes in OIDC) allow your application to specify the desired set of user data for each identity verification process. The attributes an application should request depend on which user information your application needs.

After the end-user consents to share the requested attributes and completes an identity verification process, you can retrieve their personal details.

itsme® services and attributes

With itsme®, specific attributes map to different scenarios (itsme® services) to verify a person's digital identity.

The scopes/attributes you specify in your authorization request determine which itsme® service you trigger for your end-users. The tables on this page show which scopes/attributes result in an Authentication or an Identification service.

For details about the itsme® services offered by Signicat, see the About itsme® documentation.

OIDC scopes and claims

With OIDC, you specify scopes in the authorization request that triggers an identity verification flow.

After the end-user verifies themselves and the flow is complete, you can retrieve the claims in the ID Token or through the UserInfo endpoint.

OIDC Authentication service

Use any combination of the following OIDC scopes in your request to perform an itsme® Authentication service:

ScopeOIDC ClaimExampleDescription
namenameJane DoeFull name of the end-user including first name, last name, titles and suffixes.
namegiven_nameJaneFirst name of the end-user.
namefamily_nameDoeLast name of the end-user.
Subject ID for login

The sub claim is a string that uniquely identifies a given user account. The benefit of using a sub claim is that it 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 identifier (sub claim in the ID Token) to log in a given end-user to your application.

Important

Sending a request containing scopes for Authentication and Identification defaults the process to an Identification service.

For example, a request with name, date-of-birth and nin leads to an Identification service.

OIDC Identification service

Use any combination of the following OIDC scopes in your request to perform an itsme® Identification service:

ScopeOIDC ClaimExampleDescription
profilenameJane DoeFull name of the end-user including first name, last name, titles and suffixes.
profilegiven_nameJaneFirst name of the end-user.
profilefamily_nameDoeLast name of the end-user.
profilegenderfemaleBiological sex of the end-user. Possible values are : female, male, unknown, n/a. Note that for Belgian end-users only female or male values are available.
profilebirthdate1899-12-31Date of birth of the end-user represented as a string in YYYY-MM-DD date format.
profilelocaleenEnd-user mobile phone language in string format. Available values are: nl, fr, de, en.
picturepicturehttps://<ACCOUNT_DOMAIN>/idps/oidc-vendor/itsme/picture?token=XReturns a URL pointing to the ID picture of the end-user. The URL refers to an image file (for example, a JPEG, JPEG2000, or PNG). The image is the raw (unprocessed) photograph of the person's face (portrait), as displayed on the ID document. URLs expire three minutes after the end-user authenticates.
date-of-birthbirthdate1899-12-31Date of birth of the end-user represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or more.
ninnin81042419835The national identity number of the end-user.
ninnin_typePERSONThe type of national identity number.
ninnin_issuing_countryBEThe country issuing the identity number.
emailemailtest@itsme.beEmail address of the end-user.
phonephone_number+32 453519681Phone number of the end-user represented as a string with format [+][country_code] [number].
addressaddress{"formatted": "Rue Royale 82 1000 Bruxelles"}Postal address of the end-user. Formatted as JSON object containing some (or all of) these fields: {"formatted": [street_address] [postal_code] [locality]}.
nationalitynationalityNationality of the end-user. The format depends on the ID document: for Belgian ID documents this is a string; for Dutch ID documents this is in the ISO 3166-1 alpha-3 format.
place-of-birthplace_of_birthBruxellesPlace of birth of end-user.
country-of-birthcountry_of_birthCountry of birth.
itsme-eiditsme_eid123-4567890-02ID document number. May vary per country.

The Belgian ID document number is a string of 12 digits in the form xxx-xxxxxxx-yy where yy is a check digit calculated as the remainder of dividing xxxxxxxxxx by 97 (if the remainder is 0, the check number is set to 97).

Other EU/EEA/Swiss ID document numbers start with a letter followed by nine digits, in the form B xxxxxxx xx.
itsme-eiditsme_issuance_localityPlace where the ID document was issued.
itsme-eiditsme_validity_from1899-01-31T00:00:00+00ZBelgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601.
itsme-eiditsme_validity_to1899-01-31T00:00:00+00ZBelgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601.
itsme-eiditsme_read_date1899-01-31T00:00:00+00ZThe date when the end-user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format, specified by ISO 8601.
itsme-eiditsme_national_number860224 025 08National registration number ( "Rijksregisternummer"); the unique identification number of natural persons registerd in Belgium. It comprises 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the date of birth, xxx is a sequential number (odd for males and even for females) and cd a check-digit.
itsme-deviceitsme_osiOSThe device operating system. Available values: ANDROID, iOS.
itsme-deviceitsme_app_nameThe application name.
itsme-deviceitsme_app_releaseThe application current release.
itsme-deviceitsme_device_labelThe name of the device.
itsme-deviceitsme_debug_enabledfalseBoolean that specifies whether debug mode is activated.
itsme-deviceitsme_device_idDevice identifier.
itsme-deviceitsme_os_releaseThe version of the OS running on the device.
itsme-deviceitsme_manufacturerThe brand of the device manufacturer.
itsme-deviceitsme_device_lock_levelDevice lock level.
itsme-deviceitsme_sms_enabledtrueTrue if device can send an SMS. On iOS, this means it’s an iPhone.
itsme-deviceitsme_rootedfalseSpecifies if it is a rooted device. This value is always false.
itsme-deviceitsme_imeiIMEI number of device.
itsme-deviceitsme_device_modeliPhone 7The model of the device.
itsme-deviceitsme_sdk_releaseVersion of SDK on device.
Data in response

Note that itsme® may not return values for some of the claims. When a claim is not returned, the corresponding data is omitted from the JSON object of the response.

Country coverage

itsme® returns a subset of claims data for documents issued in countries other than Belgium. For details, visit the official documentation of claims at https://belgianmobileid.github.io/doc/claims/.

OIDC response example

ID token:

{
"iss": "https://<YOUR_SIGNICAT_DOMAIN>/auth/open",
"nbf": 1712237928,
"iat": 1712237928,
"exp": 1712238528,
"aud": "<OIDC_CLIENT_ID>",
"amr": [
"external"
],
"at_hash": "0zAbHkX...IeNDhkFoWlhKg",
"sid": "8930E9EC6FAF...874DF7BA6FC907383",
"sub": "tXOq9614vLHkXBkE...ZGQO02Fc98IPaHq6iRwK-ytA=",
"auth_time": 1712237927,
"idp": "itsme",
"email": "test@itsme.be",
"phone_number": "+32 453519681",
"name": "Maxence Legrand",
"family_name": "Legrand",
"given_name": "Maxence",
"gender": "female",
"birthdate": "1981-04-24",
"address": {
"formatted": "Rue Royale 82 1000 Bruxelles"
},
"idp_issuer": "https://idp.e2e.itsme.services/v2",
"transaction_id": "355f42c4-a1ec-a...-87af-1eaad9a89435",
"sandbox": true
}

UserInfo:

{
"idp_id": "rpx5rrbsn4ktvh...q4uh2iepsdat34i9vf",
"name": "Maxence Legrand",
"family_name": "Legrand",
"given_name": "Maxence",
"gender": "female",
"birthdate": "1981-04-24",
"email": "test@itsme.be",
"address": {
"formatted": "Rue Royale 82 1000 Bruxelles",
"street_address": "Rue Royale 82",
"locality": "Bruxelles",
"postal_code": "1000"
},
"phone_number": "+32 453519681",
"nin": "81042419835",
"nin_type": "PERSON",
"sub": "tXOq9614vLHkXBkE...ZGQO02Fc98IPaHq6iRwK-ytA=",
"idp_issuer": "https://idp.e2e.itsme.services/v2"
}

Signicat Authentication REST API attributes

The Signicat Authentication REST API supports the following request attributes for itsme®.

REST API Authentication service

Use any combination of the following attributes in your request to perform an itsme® Authentication service:

AttributeExampleDescription
nameJane DoeFull name of the end-user including first name, last name, titles and suffixes.
firstNameJaneFirst name of the end-user.
lastNameDoeLast name of the end-user.
Important

Sending a request containing scopes for Authentication and Identification defaults the process to an Identification service.

For example, a request with name, dateOfBirth and nin leads to an Identification service.

REST API Identification service

Use any combination of the following attributes in your request to perform an itsme® Identification service:

AttributeSub-field (response)ExampleDescription
nameJane DoeFull name of the end-user including first name, last name, titles and suffixes.
firstNameJaneFirst name of the end-user.
lastNameDoeLast name of the end-user.
genderfemaleBiological sex of the end-user. Possible values are : female, male, unknown, n/a. Note that for Belgian end-users only female or male values are available.
dateOfBirth1899-12-31Date of birth of the end-user represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or older.
localeenEnd-user mobile phone language in string format. Available values are: nl, fr, de, en.
picturehttps://<ACCOUNT_DOMAIN>/idps/oidc-vendor/itsme/picture?token=XReturns a URL pointing to the ID picture of the end-user. The URL refers to an image file (for example, a JPEG, JPEG2000, or PNG). The image is the raw (unprocessed) photograph of the person's face (portrait), as displayed on the ID document. URLs expire three minutes after the end-user authenticates.
ninvalue81042419835The national identity number of the end-user.
nintypePERSONThe type of national identity number.
ninissuingCountryBEThe country issuing the identity number.
emailtest@itsme.beEmail address of the end-user.
phoneNumber+32 453519681Phone number of the end-user represented as a string with format [+][country_code] [number].
addressRue Royale 82 1000 BruxellesPostal address of the end-user. A string containing some (or all of) these fields: [street_address] [postal_code] [locality].
nationalityNationality of the end-user. The format depends on the ID document: for Belgian ID documents this is a string; for Dutch ID documents this is in the ISO 3166-1 alpha-3 format.
placeOfBirthBruxellesPlace of birth of end-user.
countryOfBirthCountry of birth.
itsmeEid123-4567890-02ID document number. May vary per country.

The Belgian ID document number is a string of 12 digits in the form xxx-xxxxxxx-yy where yy is a check digit calculated as the remainder of dividing xxxxxxxxxx by 97 (if the remainder is 0, the check number is set to 97).

Other EU/EEA/Swiss ID document numbers start with a letter followed by nine digits, in the form B xxxxxxx xx.
itsmeIssuanceLocalityPlace where the ID document was issued.
itsmeValidityFrom1899-01-31T00:00:00+00ZBelgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601.
itsmeValidityTo1899-01-31T00:00:00+00ZBelgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601.
itsmeReadDate1899-01-31T00:00:00+00ZThe date when the end-user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format, specified by ISO 8601.
itsmeNationalNumber860224 025 08National registration number ( "Rijksregisternummer"); the unique identification number of natural persons registerd in Belgium. It comprises 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the date of birth, xxx is a sequential number (odd for males and even for females) and cd a check-digit.
itsmeOsiOSThe device operating system. Available values: ANDROID, iOS.
itsmeAppNameThe application name.
itsmeAppReleaseThe application current release.
itsmeDeviceLabelThe name of the device.
itsmeDebugEnabledfalseBoolean that specifies whether debug mode is activated.
itsmeDeviceIdDevice identifier.
itsmeOsReleaseThe version of the OS running on the device.
itsmeManufacturerThe brand of the device manufacturer.
itsmeDeviceLockLevelDevice lock level.
itsmeSmsEnabledtrueTrue if device can send an SMS. On iOS, this means it’s an iPhone.
itsmeRootedfalseSpecifies if it is a rooted device. This value is always false.
itsmeImeiIMEI number of device.
itsmeDeviceModeliPhone 7The model of the device.
itsmeSdkReleaseVersion of SDK on device.
Data in response

Note that itsme® may not return values for some of the attributes. When an attribute is not returned, the corresponding data is omitted from the JSON object of the response.

Country coverage

itsme® returns a subset of the data for documents issued in countries other than Belgium. For details, visit the official documentation of claims at https://belgianmobileid.github.io/doc/claims/.

Authentication API response example

Here is a section of the response showing the user information attributes:

{
...
"id": "4ccb8a1b-6f40-e146-af1b-15f1c6eabb56",
"subject": {
"id": "tXOq9614vLHkXBkENWcZGQO02Fc98IPaHq6iRwK-ytA=",
"idpId": "rpx5rrbsn4ktvhm3m0q4uh2iepsdat34i9vf",
"name": "Maxence Legrand",
"firstName": "Maxence",
"lastName": "Legrand",
"dateOfBirth": "1981-04-24",
"nin": {
"value": "81042419835",
"issuingCountry": "BE",
"type": "PERSON"
},
"address": "Rue Royale 82 1000 Bruxelles",
"placeOfBirth": "Bruxelles",
},
...
}
Use ID for login

The id field in the JSON of the response from the API is a string that uniquely identifies a given user account. The benefit of using the ID is that it 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 identifier (id field in the JSON of the response) to log in a given end-user to your application.

SAML 2.0 attributes

Integrating with SAML 2.0, allows you to use the following request attributes for itsme®:

SAML Authentication service

Use any combination of the following attributes in your request to perform an itsme® Authentication service:

AttributeExampleDescription
nameJane DoeFull name of the end-user including first name, last name, titles and suffixes.
firstNameJaneFirst name of the end-user.
lastNameDoeLast name of the end-user.
Important

Sending a request containing scopes for Authentication and Identification defaults the process to an Identification service.

For example, a request with name, dateOfBirth and nin leads to an Identification service.

SAML Identification service

Use any combination of the following attributes in your request to perform an itsme® Identification service:

AttributeExampleDescription
nameJane DoeFull name of the end-user including first name, last name, titles and suffixes.
firstNameJaneFirst name of the end-user.
lastNameDoeLast name of the end-user.
genderfemaleBiological sex of the end-user. Possible values are: female, male, unknown, n/a. Note that for Belgian end-users only female or male values are available.
dateOfBirth1899-12-31Date of birth of the end-user represented as a string in YYYY-MM-DD date format. itsme® users are always 16 years old or older.
localeenEnd-user mobile phone language in string format. Available values are: nl, fr, de, en.
picturehttps://<ACCOUNT_DOMAIN>/idps/oidc-vendor/itsme/picture?token=XReturns a URL pointing to the ID picture of the end-user. The URL refers to an image file (for example, a JPEG, JPEG2000, or PNG). The image is the raw (unprocessed) photograph of the person's face (portrait), as displayed on the ID document. URLs expire three minutes after the end-user authenticates.
nin81042419835Response contains three separate fields for nin, nin.type and nin.issuingCountry, which represent respectively the national identity number of the end-user, the type of national identity number and the country issuing the identity number.
emailtest@itsme.beEmail address of the end-user.
phoneNumber+32 453519681Phone number of the end-user represented as a string with format [+][country_code] [number].
addressRue Royale 82 1000 BruxellesPostal address of the end-user, containing some (or all of) these fields: [street_address] [postal_code] [locality].
nationalityNationality of the end-user. The format depends on the ID document: for Belgian ID documents this is a string; for Dutch ID documents this is in the ISO 3166-1 alpha-3 format.
placeOfBirthBruxellesPlace of birth of the end-user.
countryOfBirthCountry of birth of the end-user.
itsmeEid123-4567890-02ID document number. May vary per country.

The Belgian ID document number is a string of 12 digits in the form xxx-xxxxxxx-yy where yy is a check digit calculated as the remainder of dividing xxxxxxxxxx by 97 (if the remainder is 0, the check number is set to 97).

Other EU/EEA/Swiss ID document numbers start with a letter followed by nine digits, in the form B xxxxxxx xx.
itsmeIssuanceLocalityPlace where the ID document was issued.
itsmeValidityFrom1899-01-31T00:00:00+00ZBelgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601.
itsmeValidityTo1899-01-31T00:00:00+00ZBelgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601.
itsmeReadDate1899-01-31T00:00:00+00ZThe date when the end-user's document was read for the last time, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format, specified by ISO 8601.
itsmeNationalNumber860224 025 08National registration number ( "Rijksregisternummer"); the unique identification number of natural persons registerd in Belgium. It comprises 11 digits in the form YY.MM.DD-xxx.cd where YY.MM.DD is the date of birth, xxx is a sequential number (odd for males and even for females) and cd a check-digit.
itsmeOsiOSThe device operating system. Available values: ANDROID, iOS.
itsmeAppNameThe application name.
itsmeAppReleaseThe application current release.
itsmeDeviceLabelThe name of the device.
itsmeDebugEnabledfalseBoolean that specifies whether debug mode is activated.
itsmeDeviceIdDevice identifier.
itsmeOsReleaseThe version of the OS running on the device.
itsmeManufacturerThe brand of the device manufacturer.
itsmeDeviceLockLevelDevice lock level.
itsmeSmsEnabledtrueTrue if device can send an SMS. On iOS, this means it’s an iPhone.
itsmeRootedfalseSpecifies if it is a rooted device. This value is always false.
itsmeImeiIMEI number of device.
itsmeDeviceModeliPhone 7The model of the device.
itsmeSdkReleaseVersion of SDK on device.
Data in response

Note that itsme® may not return values for some of the attributes. When an attribute is not returned, the corresponding data is omitted from the JSON object of the response.

Country coverage

itsme® returns a subset of the data for documents issued in countries other than Belgium. For details, visit the official documentation of claims at https://belgianmobileid.github.io/doc/claims/.

SAML 2.0 response example

The following SAML response contains the outcome of an Identification service with attributes nin, name, email:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="<YOUR_SAML_ACS_ENDPOINT>" ID="_79c74fabd7a896ee879729c92ca6c231" InResponseTo="_064f5303e14c84a59d7eaa24b6cd3558" IssueInstant="2024-04-04T11:56:12.648Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
https://<YOUR_SIGNICAT_DOMAIN>/auth/saml
</saml2:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
...
</ds:Signature>
<saml2p:Status>
<saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</saml2p:Status>
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_d9da2112740b886681bf7da6185d986f" IssueInstant="2024-04-04T11:56:12.657Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<saml2:Issuer>
https://<YOUR_SIGNICAT_DOMAIN>/auth/saml
</saml2:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
...
</ds:Signature>
<saml2:Subject>
<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="https://idp.e2e.itsme.services/v2">
tXOq9614vLHkXBkENW...QO02Fc98IPaHq6iRwK-ytA=
</saml2:NameID>
<saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml2:SubjectConfirmationData InResponseTo="_064f5303e14c84a59d7eaa24b6cd3558" NotOnOrAfter="2024-04-04T11:58:12.657Z" Recipient="<YOUR_SAML_ACS_ENDPOINT>"/>
</saml2:SubjectConfirmation>
</saml2:Subject>
<saml2:Conditions NotBefore="2024-04-04T11:56:07.657Z" NotOnOrAfter="2024-04-04T11:58:12.657Z">
<saml2:AudienceRestriction>
<saml2:Audience>
https://<YOUR_SIGNICAT_DOMAIN>/broker/authn/saml
</saml2:Audience>
</saml2:AudienceRestriction>
</saml2:Conditions>
<saml2:AttributeStatement>
<saml2:Attribute Name="name">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
Maxence Legrand
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="nin">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
81042419835
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="nin.type">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
PERSON
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="email">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
test@itsme.be
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="idpId">
<saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">
rpx5rrbsn4ktvhm3m0...uh2iepsdat34i9vf
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
<saml2:AuthnStatement AuthnInstant="2024-04-04T11:56:12.657Z" SessionIndex="fbd7098e-f7bd-4291-820a-70c9c2c0dff0">
<saml2:AuthnContext>
<saml2:AuthnContextClassRef>
urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
</saml2:AuthnContextClassRef>
<saml2:AuthenticatingAuthority>
https://idp.e2e.itsme.services/v2
</saml2:AuthenticatingAuthority>
</saml2:AuthnContext>
</saml2:AuthnStatement>
</saml2:Assertion>
</saml2p:Response>