# 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.

Page contents

Available attributes
OIDC scopes and claims
Signicat Authentication REST API attributes
SAML 2.0 attributes

# 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:

Scope	OIDC Claim	Example	Description
`name`	`name`	Jane Doe	Full name of the end-user including first name, last name, titles and suffixes.
	`given_name`	Jane	First name of the end-user.
	`family_name`	Doe	Last name of the end-user.
`email`	`email`	test@itsme.be	Email address 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:

Scope	OIDC Claim	Example	Description
`profile`	`name`	Jane Doe	Full name of the end-user including first name, last name, titles and suffixes.
	`given_name`	Jane	First name of the end-user.
	`family_name`	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.
	`birthdate`	1899-12-31	Date of birth of the end-user represented as a string in `YYYY-MM-DD` date format.
	`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_type`	PERSON	The type of national identity number.
	`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 (opens new window) 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_issuance_locality`		Place where the ID document was issued.
	`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_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_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_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_app_name`		The application name.
	`itsme_app_release`		The application current release.
	`itsme_device_label`		The name of the device.
	`itsme_debug_enabled`	false	Boolean that specifies whether debug mode is activated.
	`itsme_device_id`		Device identifier.
	`itsme_os_release`		The version of the OS running on the device.
	`itsme_manufacturer`		The brand of the device manufacturer.
	`itsme_device_lock_level`		Device lock level.
	`itsme_sms_enabled`	true	True if device can send an SMS. On iOS, this means it’s an iPhone.
	`itsme_rooted`	false	Specifies if it is a rooted device. This value is always false.
	`itsme_imei`		IMEI number of device.
	`itsme_device_model`	iPhone 7	The model of the device.
	`itsme_sdk_release`		Version 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/ (opens new window).

# 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.
`email`	test@itsme.be	Email address 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:

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.
	`type`	PERSON	The type of national identity number.
	`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 (opens new window) 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.

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/ (opens new window).

# 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:

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.
`email`	test@itsme.be	Email address 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:

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 (opens new window) 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.

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

# 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>

← Go to production