Overview

itsme® API is based on the Authorization Code Flow of OpenID Connect 1.0. The API can be used to verify your end-users’ identity and obtain some information about them. For the exact user data that can be requested, please see the Authorization Request parameters.

The diagram below describes the Identification process and how your systems should integrate with itsme® :

To get to this result please make sure you

1. add itsme® button to your front-end page so the user can indicate he wishes to authenticate with itsme® : itsme® button specifications.
2. create the Authorization Request to authenticate the User. This request will redirect the user to the itsme® app. itsme® will then authenticates the user by asking him
   • to enter his phone number on the itsme® sign-in page
   • authorize the release of some information to your application
   • to provide his credentials (itsme® code, fingerprint or FaceID)
   
   It is also in this Authorization Request that you will be able to request claims about the user and the Identification event.
3. collect the Authorization Code once the user has been authenticated and redirected by itsme® to your mobile or web application.
4. exchange the Authorization Code for an ID token (e.g. identifying the user) and an Access Token.
5. Obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint if the required claims are not returned in the ID token.
6. Confirm the success of the operation and display a success message.

Onboarding

To make use of our services, you will need to contact our Customer Care team at onboarding@itsme-id.com. Based on your requirements, they will configure for you a new partner in our database. You will receive the clientID corresponding to this partner, that you will need to include in your Authorization Request.

Each partner can contain multiple “services”. Each service should correspond to one user flow at your side and can be of type Authentication, Identification or Confirmation. The service code will also be required in your Authorization Request.

For each service, you will have to provide one or a few “redirect_uri”, which are the landing page(s) where the end user will be sent after authenticating with itsme®. Only the URIs whitelisted in a service will be allowed in your Authorization Request, so they have to be fully determined before you can use the service. This whitelisting works on an “exact match” basis, including the full (case sensitive) path and query string so please communicate the exact string you are planning to use in your Authorization Request.

Guides

Generate itsme® button

First, you will need to create a button to allow your users to authenticate with itsme®. Check the Button design guide before you start the integration.

Upon clicking this button, the user will be redirected to our Front-End. itsme® then take care of their identification.

Securing the exchange of information

To protect the exchange of sensitive information and ensure the requested information gets issued to a legitimate application and not some other party, the OpenID Connect protocol uses JSON Web Token (JWT) which can be signed and/or encrypted. Among the methods described in OpenID specification, itsme® supports 2 authentication methods to secure communications between your backend and itsme®:

• "Private key JWT" is based on a public/private key pair (asymmetric encryption). It is therefore the most secure option
• "Client secret" is based on a shared Secret key (symmetric encryption). It can be easier to implement in some cases

Public-private key pair and JWKSet URI

This method uses a pair of keys (1 public, 1 private) to encrypt and decrypt senders’ and recipients’ sensitive data. It is also known as public-key cryptography or asymetric encryption.

You can retrieve the itsme® JWK Set from the URI mentioned as jwks_uri in our itsme® Discovery document.

Secret key method

Secret key cryptography method uses the same secret key to encrypt and decrypt sensitive information. This approach is the inverse of public- and private-key encryption.

This method requires the exchange of a static secret to be held by both the sender and the data receiver. The secret value will be provided by itsme® when registering your project.

Key rotation procedure

for public-private key pair and JWKSet URI

itsme® backend has cache mechanism in place, which is sporadic (from 30min to 24h). During this time, we will keep on using old keys.

Rotating signing key:

• Add the new key to JWK set, with a new “kid”
• Start using the new key to sign JWTs
• When the flow is validated with the new key, remove the old one from the JWK set

Rotating encryption key:

• Replace the old key with the new one in JWK set, but still support old and new keys in decryption process
• Wait 24h (or wait for “max-age” amount of time, if specified)
• Decommission the old key completely

Changing the key could come along with changing the jwkset url. If that is the case, communicate new available jwkset url to onboarding@itsme-id.com. It is not be possible to be perfectly in sync, a few failed flows should be expected in the lapse of time between jwkset url update and the key update at the partner’s side. Smoother way would be:

• Copy the old jwkSet on the new URL
• the URL is communicated & registered by itsme®
• Rotate the keys in the jwkSet on the new URL as per rotating keys info above

for secret key method

Please, reach out to onboarding@itsme-id.com in case the secret key should be rotated.

PKCE-enhanced flow

Whatever the chosen authentication method, itsme® also supports an extra security extension named Proof of Key for Code Exchange (PKCE). This additionnal layer of security is intended to mitigate some Authorization Code interception attacks. For this mechanism to achieve its full potential, PKCE has to be made mandatory in your flow, which is an option we can enable for you (strongly recommended). Please ask our onboarding team to do so when registering your project.

PKCE implies choosing a random string, named code_verifier, and then generating a SHA256 hash of that string, named code_challenge. The code_challenge has to be sent along with the Authorization Request, while the code_verifier must be sent with the Token Request, allowing our backend to make sure both requests are issued by the same source.

code_challenge can then be obtained via this kind of instructions:

var hash = code_verifier.createHash('sha256');
var code_challenge = base64url.encode(hash);

Signing, encrypting and decoding JWTs

Libraries implementing JWT and the JOSE specs JWS, JWE, JWK, and JWA are listed here. For testing purposes only, we could advise the use of https://mkjwk.org/ for JWK generation and https://mkjose.org/ for payload check => these are 2 open-source tools which will help you visualize JWK mechanisms, client assertion construct. Please DO NOT generate production private keys on any website. Rather opt for the relevant SDK library mentioned here.

Certificates and website security

itsme® requires https connections to guarantee security. With the https protocol, a web site operator obtains a certificate by applying to a certificate authority with a certificate signing request. The certificate request is an electronic document that contains the web site name, company information and the public key. The certificate provider signs the request, thus producing a public certificate. During web browsing, this public certificate is served to any web browser that connects to the web site and proves to the web browser that the provider believes it has issued a certificate to the owner of the web site.

A certificate provider can opt to issue three types of certificates, each requiring its own degree of vetting rigor. In order of increasing rigor (and naturally, cost) they are: Domain Validation, Organization Validation and Extended Validation.

The Domain Validation certificate doesn’t provide sufficient identity guarantees to itsme. So, only the Organization Validation and Extended Validation certificates are supported. For example, using the Let’s Encrypt open certificate authority is not suffcient because it only provide standard Domain Validation certificates.

Handling responses

Whenever a partner is sending a request to the itsme OIDC endpoints he will get a response back. According to the OIDC protocol, and depending on the endpoint that was contacted, partners can get a

• response where some parameters are added to the query component of the redirection URI using the application/x-www-form-urlencoded format, or
• response displayed directly on our itsme® sign-in page ;
• response using the application/json media type

Alongside the type of response an HTTP status code is sent that shows whether the request was successful or not. If it was not, you can tell by the code and the message in the response what went wrong, why it went wrong and whether there is something the partner can do about it.

A successful response

An HTTP status 200 OK or 302 Found is issued whenever your request was a success. You see this type of response in our examples like the one where we successfully retrieve the Token Response :

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
    yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
    NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
    fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
    AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
    Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
    NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
    QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
    K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
    XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "expires_in": 3600,
}

The error responses

Things will sometimes go wrong. So, OpenID Connect defines a number of rules regarding the format of errors returned from our endpoints.

Authorization Endpoint errors

If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid,… the Authorization Endpoint will inform you of the error our itsme® sign-in page.

If the User denies the access request or the User authentication fails, the Authorization Endpoint will inform you by adding the following parameters to the query component of the redirection URI using the application/x-www-form-urlencoded format :

For example :

HTTP/1.1 302 Found Location: https://client.example.com/cb?error=access_denied&state=xyz

Token Endpoint errors

If the request fails the Token Endpoint responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters in the entity-body of the HTTP response using the application/json media type :

For example :

HTTP/1.1 400 Bad Request 
Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache 

{ 
  "error":"invalid_request" 
}

UserInfo Endpoint errors

When a request fails, the UserInfo Endpoint responds using the appropriate HTTP status code (typically, 400, 401, 403, or 405) and includes specific error codes in the response.

For example :

HTTP/1.1 401 Unauthorized 
WWW-Authenticate: Bearer realm="example"

Revocation Endpoint errors

If the request fails the Revoke Endpoint responds with an HTTP 400 (Bad Request) status code and includes the fllowing parameters in the entity-body of the HTTP response using the application/json media type :

For example:

HTTP/1.1 400 Bad Request 
Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache 

{ 
  "error":"invalid_request" 
}

Mapping the user

Mapping using sub claim

To sign in successfully in your web desktop, mobile web or mobile application, a given user must be mapped to a user account in your database. By default, your application Server will use the subject identifier, or sub claim, in the ID Token to identify and verify a user account. The sub claim is a string that uniquely identifies a given user account. The benefit of using a sub claim is that it will not change, even if other user attributes (email, phone number, etc) associated with that account are updated.

If no user record is storing the sub claim value, then you should allow the user to associate his new or existing account to the sub.

Benefit of sub claim

The benefit of using a sub claim is that it will not change, not even if other user attributes (email, phone number, etc.) associated with that account are updated.

Deleting and re-creating an itsme® account

In a limited number of cases (e.g. technical issue,…) a user could ask itsme® to ‘delete’ his account. As a result the specific account will be ‘archived’ (for compliancy reasons) and thus also the unique identifier(s) (e.g. “sub”).

If the same user would opt to re-create an itsme® afterwards, he will need to re-bind his itsme® account with your application server, in the same way as for the initial binding. After successful re-binding you will need to overwrite the initial reference with the new sub claim value in your database.

User Data

itsme® is making a range of user data available for its partners. Those can be requested through the Authorization Request, individually as “claims” or as part of a broader “scope”. These claims can be split in 2 categories:

User Attributes

User attributes are saying something about the end user. They are part of the identity of a person and we retrieve them from an identity document (ID card, passport…). Examples: name, address, birthdate, etc.

Metadata

Metadata are saying something about the data we have for an end user. They are not directly related to a person, but rather to an information about this person. Examples are the validityTo, the verificationDate etc. Those metadata, if requested, will only return values relating to the user attributes that are also requested. The metadata will then return an object containing one value for each relevant user attribute.

Examples:

• The verificationDate is a metadata that has a value for most user attributes. So requesting the verificationDate AND the birthdate AND the given_name will return the following pattern for verificationDate:

"http://itsme.services/v2/claim/verificationDate": {
		"birthdate": "2023-06-01T13:04:26Z",
		"given_name": "2023-06-01T13:04:26Z"
	}

• Requesting only the verificationDate will return nothing, as it only returns values for other requested attributes.

• The validityTo metadata only has a value for BEeidSn and IDDocumentSN (because other attributes don’t have an expiry date). So validityTo will only return a value if BEeidSn and/or IDDocumentSN is also requested. Even if other attributes are requested, validityTo will not return a value for those other attributes.

API reference

itsme® Discovery Document

• Public- and private-key
• Secret key

• GET https://idp.[e2e/prd].itsme.services/v2/.well-known/openid-configuration

  To simplify implementations and increase flexibility, OpenID Connect allows the use of a Discovery Document, a JSON document containing key-value pairs which provide details about itsme® configuration, such as the

  Authorization, Token and userInfo Endpoints Supported claims ...

• GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/.well-known/openid-configuration

  To simplify implementations and increase flexibility, OpenID Connect allows the use of a Discovery Document, a JSON document containing key-value pairs which provide details about itsme® configuration, such as the

  Authorization, Token and userInfo Endpoints Supported claims ...

Authorization Request

• Public- and private-key
• Secret Key

• GET https://idp.[e2e/prd].itsme.services/v2/authorization

• GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/authorize

Parameters

Response

302 application/x-www-form-urlencoded

Example

• Public- and private-key
• Secret key

• Request

  GET /v2/authorization HTTP/1.1
  Host: server.example.com
  
  response_type=code
  &client_id=abcd1234
  &redirect_uri=https://client.example.org/cb
  &scope=openid+service:EXAMPLE+profile+eid+phone+email+address
  &state=anystate
  &nonce=anonce
  &prompt=login
  &max_age=1
  &claims={"id_token":{
    "name":null,
    "gender":null,
  	"http://itsme.services/v2/claim/BENationalNumber":null,
  	"http://itsme.services/v2/claim/claim_citizenship":null,
  	"http://itsme.services/v2/claim/place_of_birth":null,
  	"http://itsme.services/v2/claim/physical_person_photo":null,
  	"http://itsme.services/v2/claim/birthdate_as_string":null,
  	"http://itsme.services/v2/claim/validityFrom":null,
  	"http://itsme.services/v2/claim/validityTo":null,
  	"http://itsme.services/v2/claim/IDDocumentSN":null}}
  

  Response

  HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj
  

• Request

  GET /authorize HTTP/1.1
  Host: server.example.com
  
  response_type=code
  &client_id=abcd1234
  &redirect_uri=https://client.example.org/cb
  &scope=openid+service:EXAMPLE+profile+eid+phone+email+address
  &state=anystate
  &nonce=anonce
  &prompt=login
  &max_age=1
  &claims={"id_token":{
    "name":null,
    "gender":null,
  	"http://itsme.services/v2/claim/BENationalNumber":null,
  	"http://itsme.services/v2/claim/claim_citizenship":null,
  	"http://itsme.services/v2/claim/place_of_birth":null,
  	"http://itsme.services/v2/claim/physical_person_photo":null,
  	"http://itsme.services/v2/claim/birthdate_as_string":null,
  	"http://itsme.services/v2/claim/validityFrom":null,
  	"http://itsme.services/v2/claim/validityTo":null,
  	"http://itsme.services/v2/claim/IDDocumentSN":null}}
  

  Response

  HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj
  

Token Request

• Public- and private-key
• Secret key

• POST https://idp.[e2e/prd].itsme.services/v2/token

  To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the public- and private-key pair method.

  Parameters

  grant_type REQUIRED	Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID token and access token.
  code REQUIRED	The intermediate opaque credential received in the Authorization Response.
  redirect_uri REQUIRED	It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
  code_verifier OPTIONAL	High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.
  client_assertion_type REQUIRED	Specifies the type of assertion. Set this to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
  client_assertion REQUIRED	Is a set of identity and security information, in the form of a JWT, used as an authentication method. To ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code, the JWT MUST be signed, and MAY also be encrypted. If both signing and encryption are performed, it MUST be signed then encrypted, with the result being a Nested JWT (refer to this page for more information). The JWT contains the following claims. iss REQUIRED The issuer of the token. This value MUST be the same as the client_id. sub REQUIRED The subject of the token. This value MUST be the same as the client_id. aud REQUIRED The full URL of the resource you're using the JWT to authenticate to. Set this to https://idp.[e2e/prd].itsme.services/v2/token. jti REQUIRED An unique identifier for the token, containing maximum 255 characters. exp REQUIRED The expiration time of the token in seconds since January 1, 1970 UTC. iat OPTIONAL The time at which the JWT was issued.

  Response

  200 application/json

  access_token	Allows an application to retrieve consented user information from the UserInfo Endpoint.
  token_type	Provides your application with the information required to successfully utilize the access token. Returned value is Bearer..
  id_token	A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).

• POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/token

  To assert the identity of the user, the code received previously needs to be exchanged for an ID token and access token. During this step, your application has to authenticate itself to our server using the secret key method.

  Parameters

  grant_type REQUIRED	Set this to authorization_code to tell the Token Endpoint that your application wants to exchange an authorization code for an ID koken and access token.
  client_id REQUIRED	It identifies your application. This parameter value is generated during registration.
  code REQUIRED	The intermediate opaque credential received in the Authorization Response.
  redirect_uri REQUIRED	It is the URL to which users are redirected once the authentication is complete. It MUST match the value used in the Authorization Request.
  client_secret REQUIRED	Contains the a key you reveiced when registering your application. This ensures that the request to get the id token and access token is made only from your application, and not from a potential attacker that may have intercepted the authorization code.
  code_verifier OPTIONAL	High-entropy cryptographic random string using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters. This parameter is REQUIRED if you required PKCE to be enforced.

  Response

  200 application/json

  access_token	Allows an application to retrieve consented user information from the UserInfo Endpoint.
  token_type	Provides your application with the information required to successfully utilize the access token. Returned value is Bearer.
  id_token	A security token that contains information about the authentication of an user, and potentially other requested claim data's. The id_token value is represented as a signed and encrypted JWT. So, before being able to use the ID Token claims you will have to decrypt and verify the signature (refer to this page for more information).

Example

• Public- and private-key
• Secret key

• Request

  POST /token HTTP/1.1
  Host: openid.c2id.com
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code
   &code=SplxlOBeZQQYbYS6WxSbIA
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
   &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   &client_assertion=PHNhbWxwOl ... ZT
  

  Response

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache
  
  {
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
      yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
      NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
      fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
      AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
      Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
      NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
      QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
      K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
      XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "expires_in": 3600,
  }
  

  Example of a decrypted id_token:

  {
  	"sub": "6g2k9rgglem2dttw5d51ulkxpv24phwatiu6",
  	"aud": "WXw9DMqkEv",
  	"birthdate": "1974-10-23",
  	"gender": "male",
  	"name": "John Ronald R Tolkien",
  	"iss": "https://idp.prd.itsme.services/v2",
  	"nonce": "nonce",
  	"exp": 1699538407,
  	"iat": 1699538107
  }
  

• Request

  POST /token HTTP/1.1
  Host: openid.c2id.com
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code
   &code=SplxlOBeZQQYbYS6WxSbIA
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
   &client_id=s6BhdRkqt3
   &client_secret=PHNhbWxwOl ... ZT
  

  Response

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache
  
  {
    "id_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..UPzPZWb
       Da_ZvysMK.7ZXAFd24uTT35_gzrdYeuLBPrPR3Gc8VdB7L7MgZWgS4hiP
       72URWNDPbOMLYw4xHx2CVKPGp9K0L05UeSMDcB39n_anV5nZ3BbkNsufx
       RiANOfoxx2W5jsb8Fj5W8F862wRWmClxTOosszauVhD6ZbhpJM0k9Iw7T
       CmwlmK3WMg9aE-gSNlvsjgrfB5QFmgYH2PWF1YdWZ1gCdCw3rz1XvxHPV
       yR9PfSy7SFFEoZos-2Y_rlO4R5_Oel3xy0YA_OucJVnV2x6oblxQ4TBXB
       8YMCYyk3m7aS_S_oEs-2yAGCbQgwKU9jwqytF8Yw5X_rZmcbTpdvAF5qu
       ozfnoiW2ijHxr6xlH_8cibSIjhKOHEPCBTc8AeAb9nHLGrx0H1q02o7nz
       U-TwxUayrHXLBKd72l6aD8RxwCziATzjVWnvVVR7BmvOAV8L8IY_DTGgn
       iH2NlHL6_2KVtuB8czkDjEToE-JUfuzoedja9PTzRp6paO3ZpXSQcLl6a
       6qBe526hMNEiK9VPRWPOJ8xIqwpg3mSeMjdkvSS6A9xJVH_xEy9jzts1n
       k2ge-YGrZZiQt8Do7NCd-ic7_HU8timZ_mfPFc8NDYgr0WtPefDQlC6en
       8sUcMjuhuZOx_A3cQ7Mvoq662meUbkN64z50oBoh8Drora69I85zXQwes
       sR9f4z0th2-XDDrPxPop6yuJx8vMmRQNhN55qvwxgFMTEJyvDNAVfBA9s
       FZlj4hubY3wtYP5nLADjIFLresbrsu6iFQaE7v01FUMMDXcvBi_hw-M9s
       0nBuWsQa2rZRcrVJOK9HVXUxXdUfTNL4MrrG5UzT7gdtcpesXeFVLSJtq
       7HEGlHi3xaefgo4P5GN562CGVUl41BSmoBJT9oS5YJWKJOEOfpcAhYLKM
       5iyMbgOxVz1Fz7z6Pfcd-PRcRlSQlHBXCdhP01AmRw-H_bdoKFIM1D33B
       3AmmEKD6XRe8XM79F_gwySJ3AIWUzVLpJxe1lUphzIgy5O-VleJWyKl3D
       nAkCQwvqV-P-MrjirZckzlDjjfyOlEA_KNAK-PwCvZ5Yh_Wv8f-8LXUWJ
       ewfOCZmOM5pSKYXl-oZ.hfcIWiYPCtQMheNN8FB0Ww"
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "expires_in": 3600,
  }
  

  Example of a decrypted id_token:

  {
  	"sub": "6g2k9rgglem2dttw5d51ulkxpv24phwatiu6",
  	"aud": "WXw9DMqkEv",
  	"birthdate": "1974-10-23",
  	"gender": "male",
  	"name": "John Ronald R Tolkien",
  	"iss": "https://oidc.prd.itsme.services/clientsecret-oidc/csapi/v0.1",
  	"nonce": "5468798645321",
  	"nbf": 1699538107,
  	"exp": 1699538407,
  	"iat": 1699538107
  }
  

UserInfo Request

• Public- and private-key
• Secret key

• GET https://idp.[e2e/prd].itsme.services/v2/userinfo

  The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.

  This is illustrated in the example below.

  Response

  200 application/json

  The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).

• GET https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/userinfo

  The UserInfo Endpoint returns previously consented user profile information to your application. In other words, if the required claims are not returned in the ID Token, you can obtain the additional claims by presenting the access token to the itsme® UserInfo Endpoint. This is achieved by sending a HTTP GET request to the Userinfo Endpoint, passing the access token value in the Authorization header using the Bearer authentication scheme.

  This is illustrated in the example below.

  Response

  200 application/json

  The UserInfo Response is represented as a signed and encrypted JWT. So, before being able to extract the claims you will have to decrypt and verify the signature (refer to this page for more information).

Example

Request

GET /userinfo HTTP/1.1
Host: server.example.com
Authorization: Bearer SlAV32hkKG

Response

This is an response example containing all possible claims for a Belgian account:

HTTP/1.1 200 OK
Content-Type: application/json

{
	"http://itsme.services/v2/claim/validityFrom": {
		"http://itsme.services/v2/claim/BEeidSn": "2018-11-08T00:00:00Z"
	},
	"sub": "e3xad7upx64grm14ttpnx4c586ve8gy0gp38",
	"birthdate": "1978-11-01",
	"http://itsme.services/v2/claim/claim_citizenship_as_iso": "BEL",
	"gender": "male",
	"http://itsme.services/v2/claim/birthdate_as_string": "01.11.1978",
	"http://itsme.services/v2/claim/IDDocumentType": "I",
	"iss": "https://oidc.uat.itsme.services/clientsecret-oidc/csapi/v0.1",
	"http://itsme.services/v2/claim/validityTo": {
		"http://itsme.services/v2/claim/BEeidSn": "2028-11-10T00:00:00Z"
	},
	"http://itsme.services/v2/claim/claim_citizenship": "BE",
	"locale": "FR",
	"http://itsme.services/v2/claim/issuance_locality": {
		"http://itsme.services/v2/claim/BEeidSn": "BRUXELLES"
	},
	"email": "test@itsme.be",
	"http://itsme.services/v2/claim/place_of_birth": {
		"city": "Brussels",
		"formatted": "Brussels"
	},
	"address": {
		"locality": "TONGEREN",
		"street_address": "Jekerstraat 39",
		"postal_code": "3700",
		"formatted": "Jekerstraat 39 3700 TONGEREN"
	},
	"email_verified": false,
	"http://itsme.services/v2/claim/claim_device": {
		"os": "ANDROID",
		"appName": "be.bmid.itsme.uat",
		"appRelease": "4.0.0",
		"deviceLabel": "lucye",
		"debugEnabled": false,
		"deviceId": "c22de2331dd249bba063afd3507fe3a4f",
		"osRelease": "9",
		"manufacturer": "LGE",
		"deviceLockLevel": "true",
		"rooted": false,
		"deviceModel": "LG-H870",
		"msisdn": "0032485694175"
	},
	"http://itsme.services/v2/claim/BENationalNumber": "99060427181",
	"phone_number_verified": true,
	"given_name": "George",
	"picture": "https://oidc.uat.itsme.services/clientsecret-oidc/csapi/v0.1/picture",
	"http://itsme.services/v2/claim/verificationDate": {
		"http://itsme.services/v2/claim/place_of_birth": "2023-04-12T15:02:23Z",
		"birthdate": "2023-04-12T15:02:23Z",
		"address": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/claim_citizenship_as_iso": "2023-04-12T15:02:23Z",
		"gender": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/birthdate_as_string": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/BENationalNumber": "2023-04-12T15:02:23Z",
		"given_name": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/claim_citizenship": "2023-04-12T15:02:23Z",
		"picture": "2023-04-12T15:02:23Z",
		"name": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/IDDocumentSN": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/BEeidSn": "2023-04-12T15:02:23Z",
		"family_name": "2023-04-12T15:02:23Z",
		"http://itsme.services/v2/claim/physical_person_photo": "2023-04-12T15:02:23Z"
	},
	"aud": "WXw9DMqkEv",
	"http://itsme.services/v2/claim/IDIssuingCountry": {
		"http://itsme.services/v2/claim/place_of_birth": "BEL",
		"birthdate": "BEL",
		"address": "BEL",
		"http://itsme.services/v2/claim/claim_citizenship_as_iso": "BEL",
		"gender": "BEL",
		"http://itsme.services/v2/claim/birthdate_as_string": "BEL",
		"http://itsme.services/v2/claim/BENationalNumber": "BEL",
		"given_name": "BEL",
		"http://itsme.services/v2/claim/claim_citizenship": "BEL",
		"picture": "BEL",
		"name": "BEL",
		"http://itsme.services/v2/claim/IDDocumentSN": "BEL",
		"http://itsme.services/v2/claim/BEeidSn": "BEL",
		"family_name": "BEL",
		"http://itsme.services/v2/claim/physical_person_photo": "BEL"
	},
	"name": "George Tǎnka",
	"http://itsme.services/v2/claim/IDDocumentSN": "431522485012",
	"phone_number": "+32 485694175",
	"http://itsme.services/v2/claim/BEeidSn": "431522485012",
	"family_name": "Tǎnka",
	"http://itsme.services/v2/claim/physical_person_photo": {
		"format": "image/jpeg",
		"value": "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"
	},
	"nbf": 1681314190,
	"exp": 1681314490,
	"iat": 1681314190
}

Revoke Request

• Public- and private-key
• Secret key

• Not applicable.

• POST https://oidc.[e2e/prd].itsme.services/clientsecret-oidc/csapi/v0.1/connect/revoke

  The Revocation Endpoint enables your application to notify itsme® that a previously obtained access token is no longer needed and MUST be revoked.

  Parameters

  token REQUIRED	The access_token previously obtained that you want to revoke.
  token_type_hint OPTIONAL	A hint about the type of the token submitted for revocation. You MAY pass this parameter in order to help itsme® to optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. If used, this is set to access_token because itsme® API don't support refresh tokens.

  Response

  200

  itsme® responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.

Example

• Public- and private-key
• Secret key

• Not applicable.

• Request

  POST /connect/revoke HTTP/1.1
  Host: server.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
  
  token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token
  

  Response

  HTTP/1.1 200 OK