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.
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.
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:
Scope | OIDC Claim | Example | Description |
---|---|---|---|
name | name | Jane Doe | Full name of the end-user including first name, last name, titles and suffixes. |
name | given_name | Jane | First name of the end-user. |
name | family_name | Doe | Last name of the end-user. |
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.
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:
Scope | OIDC Claim | Example | Description |
---|---|---|---|
profile | name | Jane Doe | Full name of the end-user including first name, last name, titles and suffixes. |
profile | given_name | Jane | First name of the end-user. |
profile | family_name | Doe | Last name of the end-user. |
profile | gender | female | Biological 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. |
profile | birthdate | 1899-12-31 | Date of birth of the end-user represented as a string in YYYY-MM-DD date format. |
profile | locale | en | End-user mobile phone language in string format. Available values are: nl , fr , de , en . |
picture | picture | URL pointing to a picture on the ID document of the end-user. The URL refers to an image file. | |
date-of-birth | birthdate | 1899-12-31 | Date 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. |
nin | nin | 81042419835 | The national identity number of the end-user. |
nin | nin_type | PERSON | The type of national identity number. |
nin | nin_issuing_country | BE | The country issuing the identity number. |
email | email | test@itsme.be | Email address of the end-user. |
phone | phone_number | +32 453519681 | Phone number of the end-user represented as a string with format [+][country_code] [number] . |
address | address | {"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]} . |
nationality | nationality | Nationality 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-birth | place_of_birth | Bruxelles | Place of birth of end-user. |
country-of-birth | country_of_birth | Country of birth. | |
itsme-eid | itsme_eid | 123-4567890-02 | ID document number. Differences apply per country. 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 documents format starts with a letter and nine digits in the form B xxxxxxx xx . |
itsme-eid | itsme_issuance_locality | Place where the ID document was issued. | |
itsme-eid | itsme_validity_from | 1899-01-31T00:00:00+00Z | Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. |
itsme-eid | itsme_validity_to | 1899-01-31T00:00:00+00Z | Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. |
itsme-eid | itsme_read_date | 1899-01-31T00:00:00+00Z | The 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-eid | itsme_national_number | 860224 025 08 | National registration number ( "Rijksregisternummer") is 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-device | itsme_os | iOS | The device operating system. Available values are "ANDROID" or "iOS". |
itsme-device | itsme_app_name | The application name. | |
itsme-device | itsme_app_release | The application current release. | |
itsme-device | itsme_device_label | The name of the device. | |
itsme-device | itsme_debug_enabled | false | Boolean that specifies whether debug mode is activated. |
itsme-device | itsme_device_id | Device identifier. | |
itsme-device | itsme_os_release | The version of the OS running on the device. | |
itsme-device | itsme_manufacturer | The brand of the device manufacturer. | |
itsme-device | itsme_device_lock_level | Device lock level. | |
itsme-device | itsme_sms_enabled | true | True if device can send an SMS. On iOS, this means it’s an iPhone. |
itsme-device | itsme_rooted | false | Specifies if it is a rooted device. This value is always false. |
itsme-device | itsme_imei | IMEI number of device. | |
itsme-device | itsme_device_model | iPhone 7 | The model of the device. |
itsme-device | itsme_sdk_release | Version of SDK on device. |
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.
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:
Attribute | Example | Description |
---|---|---|
name | Jane Doe | Full name of the end-user including first name, last name, titles and suffixes. |
firstName | Jane | First name of the end-user. |
lastName | Doe | Last name of the end-user. |
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:
Attribute | Sub-field (response) | Example | Description |
---|---|---|---|
name | Jane Doe | Full name of the end-user including first name, last name, titles and suffixes. | |
firstName | Jane | First name of the end-user. | |
lastName | Doe | Last name of the end-user. | |
gender | female | Biological 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. | |
dateOfBirth | 1899-12-31 | Date 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. | |
locale | en | End-user mobile phone language in string format. Available values are: nl , fr , de , en . | |
picture | URL pointing to a picture on the ID document of the end-user. The URL refers to an image file. | ||
nin | value | 81042419835 | The national identity number of the end-user. |
nin | type | PERSON | The type of national identity number. |
nin | issuingCountry | BE | The country issuing the identity number. |
email | test@itsme.be | Email address of the end-user. | |
phoneNumber | +32 453519681 | Phone number of the end-user represented as a string with format [+][country_code] [number] . | |
address | Rue Royale 82 1000 Bruxelles | Postal address of the end-user. A string containing some (or all of) these fields: [street_address] [postal_code] [locality] . | |
nationality | Nationality 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. | ||
placeOfBirth | Bruxelles | Place of birth of end-user. | |
countryOfBirth | Country of birth. | ||
itsmeEid | 123-4567890-02 | ID document number. Differences apply per country. 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 documents format starts with a letter and nine digits in the form B xxxxxxx xx . | |
itsmeIssuanceLocality | Place where the ID document was issued. | ||
itsmeValidityFrom | 1899-01-31T00:00:00+00Z | Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. | |
itsmeValidityTo | 1899-01-31T00:00:00+00Z | Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. | |
itsmeReadDate | 1899-01-31T00:00:00+00Z | The 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. | |
itsmeNationalNumber | 860224 025 08 | National registration number ( "Rijksregisternummer") is 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. | |
itsmeOs | iOS | The device operating system. Available values are "ANDROID" or "iOS". | |
itsmeAppName | The application name. | ||
itsmeAppRelease | The application current release. | ||
itsmeDeviceLabel | The name of the device. | ||
itsmeDebugEnabled | false | Boolean that specifies whether debug mode is activated. | |
itsmeDeviceId | Device identifier. | ||
itsmeOsRelease | The version of the OS running on the device. | ||
itsmeManufacturer | The brand of the device manufacturer. | ||
itsmeDeviceLockLevel | Device lock level. | ||
itsmeSmsEnabled | true | True if device can send an SMS. On iOS, this means it’s an iPhone. | |
itsmeRooted | false | Specifies if it is a rooted device. This value is always false. | |
itsmeImei | IMEI number of device. | ||
itsmeDeviceModel | iPhone 7 | The model of the device. | |
itsmeSdkRelease | Version of SDK on device. |
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.
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",
},
...
}
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:
Attribute | Example | Description |
---|---|---|
name | Jane Doe | Full name of the end-user including first name, last name, titles and suffixes. |
firstName | Jane | First name of the end-user. |
lastName | Doe | Last name of the end-user. |
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:
Attribute | Example | Description |
---|---|---|
name | Jane Doe | Full name of the end-user including first name, last name, titles and suffixes. |
firstName | Jane | First name of the end-user. |
lastName | Doe | Last name of the end-user. |
gender | female | Biological 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. |
dateOfBirth | 1899-12-31 | Date 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. |
locale | en | End-user mobile phone language in string format. Available values are: nl , fr , de , en . |
picture | URL pointing to a picture on the ID document of the end-user. The URL refers to an image file. | |
nin | 81042419835 | Response 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. |
email | test@itsme.be | Email address of the end-user. |
phoneNumber | +32 453519681 | Phone number of the end-user represented as a string with format [+][country_code] [number] . |
address | Rue Royale 82 1000 Bruxelles | Postal address of the end-user, containing some (or all of) these fields: [street_address] [postal_code] [locality] . |
nationality | Nationality 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. | |
placeOfBirth | Bruxelles | Place of birth of the end-user. |
countryOfBirth | Country of birth of the end-user. | |
itsmeEid | 123-4567890-02 | ID document number. Differences apply per country. 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 documents format starts with a letter and nine digits in the form B xxxxxxx xx . |
itsmeIssuanceLocality | Place where the ID document was issued. | |
itsmeValidityFrom | 1899-01-31T00:00:00+00Z | Belgian ID document issuance date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. |
itsmeValidityTo | 1899-01-31T00:00:00+00Z | Belgian ID card expiry date, represented as a string in YYYY-MM-DDThh:mm:ss.nnnZ date format specified by ISO 8601. |
itsmeReadDate | 1899-01-31T00:00:00+00Z | The 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. |
itsmeNationalNumber | 860224 025 08 | National registration number ( "Rijksregisternummer") is 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. |
itsmeOs | iOS | The device operating system. Available values are "ANDROID" or "iOS". |
itsmeAppName | The application name. | |
itsmeAppRelease | The application current release. | |
itsmeDeviceLabel | The name of the device. | |
itsmeDebugEnabled | false | Boolean that specifies whether debug mode is activated. |
itsmeDeviceId | Device identifier. | |
itsmeOsRelease | The version of the OS running on the device. | |
itsmeManufacturer | The brand of the device manufacturer. | |
itsmeDeviceLockLevel | Device lock level. | |
itsmeSmsEnabled | true | True if device can send an SMS. On iOS, this means it’s an iPhone. |
itsmeRooted | false | Specifies if it is a rooted device. This value is always false. |
itsmeImei | IMEI number of device. | |
itsmeDeviceModel | iPhone 7 | The model of the device. |
itsmeSdkRelease | Version of SDK on device. |
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.
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>