High Level Overview

Version: 1.2 updated on 2023-06-20

This document provides a bird's-eye overview of the Bank iD system, its technical goals, decisions and related motivations. This document should provide a starting point for Bank developers wishing to achieve compliance with the Bank iD technical specification.


  • SeP - Service Provider - A third party which is registered in the Bank iD system and intends to consume Bank APIs
  • PII - Personally Identifiable Information - End-User information like name, email address or state-issued IDs
  • AML - Anti-Money Laundering - A set of laws and regulations intended to prevent money laundering
  • KYC - Know Your Customer - A Bank API which allows SePs to gather information about End-Users
  • IdP - Identity Provider - A component on the side of the Bank which handles authorization and consent and issues tokens
  • RP - Relying Party - RP is a party using the provider's identity services. From the bank's point of view, the Relying Party is Bank iD, and for Bank iD, it is the Service Provider.

Bank iD system actors

  • Bank - An entity which provides authentication and KYC services.
  • End-User - A person (or legal entity) that has an account in the Bank and wants to use it for authentication.
  • Service Provider (SeP) - A Third party which provides service to the End-User. Uses Bank iD to get additional Bank-verified information about the End-User.
  • Bank iD - A service that sits between the SeP and the Bank.

What is Bank iD?

Bank iD acts as a middleman, between the Service Provider (SeP) and the End-User's Bank. Bank iD gives the user an option to authenticate against the SeP using their Bank account and later allows the SeP to acquire Bank verified data and Personally Identifiable Information (PII) of the End-User.

The main goals of the Bank iD system are:

  • To streamline authentication experience for the End-User during initial registration into the SeP with the End-User's pre-existing Bank account.
  • To allow Service Providers access to Bank-verified personal data for
    • Authorization - for example: Is the End-User over 18 years of age? Can I sell them alcohol?
    • PII verification - Is this End-User who they claim they are?
    • Compliance with Anti-Money Laundering (AML) laws and regulations through the use of Know Your Customer (KYC) API.
  • To give Banks an additional revenue stream using easily interoperable and monetized APIs, which will decrease SeP's barrier for entry and thus increase usage of the monetized KYC (or other) APIs exposed by the Banks.

What is Bank iD on a technical level?

Bank iD exposes two sets of REST interfaces - one for Banks and one for Service Providers. These are based on the OpenID Connect and OAuth2 specifications. The specification is followed as closely as possible to allow for easy interoperability with existing solutions and code - which SHOULD decrease overall development and maintenance costs.

The APIs are described using a set of OpenAPI specifications, namely:

High level technical decisions

Why use standards instead of making a custom-tailored solution?

  • Use of open standards such as OpenID Connect and OAuth2 allows all parties to decrease integration costs by reusing existing code and solutions.
  • Use of well defined standards removes most ambiguity and simplifies technical communication.
  • Technical communication is easier as all parties can reference the open standard and use language and technical terms defined in the standard.

Why is it important to aim for maximal standard compliance?

  • Full standard compliance allows for existing solutions and code to be used with minimal modification.
  • It reduces the quantity of bugs caused by misunderstood specification and wrong assumptions.
  • Low standard compliance may result in nasty surprising bugs that stem from code and solutions assuming standard compliance when that is not the case. These can be costly.

Why were OpenID Connect and OAuth2 selected as the standards to follow?

  • OAuth2 is a very well established authorization framework that is used by most high profile players in the IT vertical. These companies include Google, Microsoft, Facebook, Twitter, LinkedIn and many others. This implies a vast quantity of available tooling, code and solutions - Open Source or otherwise.
  • OpenID Connect is an identity layer on top of OAuth2 which improves on security and provides additional features such as discovery and session management. OpenID Connect is a relatively newer protocol; it is, however, well thought out and already in use by most of the companies above.

Why is dynamic registration required?

One of the APIs that Banks need to implement is dynamic registration. The purpose of this API is to dynamically register the SeP into the Bank's systems. This is required because:

  • This gives the Bank intelligence as to which Third Parties it does business with
  • It allows the Bank to properly display the consent screen to the End-User, including SeP specific branding, logo and TOS link.
  • It gives control over the consent screen into the hands of the Bank, rather than to the RP.
  • It allows the Bank to be standard-compliant.
  • It gives the Bank the possibility to use an already existing OpenID Connect or OAuth2 middleware in front of its IDP; this way, the Bank can just slightly modify an existing solution, rather than implement a custom one.

Which hypothetical alternatives to dynamic registration would there be?

All of the following solutions are not standard-compliant and thus incur costs mentioned above.

  • The Bank iD MAY expose additional back-channel APIs which would provide branding information for the consent screen.
    • This would force the Bank to make additional calls and thus slow down the authentication process
    • The Bank would need to fully implement this new non-standard protocol
    • It would only increase development costs for the Bank, since the Bank would still need to keep all the branding information, but now there would be an additional step to reacquire it during each authorization
    • The Bank would not be directly notified of branding changes
  • The Bank iD MAY stream branding updates over some other non-standard back channel like a Kafka queue
    • This would be exactly the same as the standard-compliant solution in the sense that the Bank would keep all the branding information
    • It would introduce another moving part, the queue server, which would need to be managed and maintained
    • In conclusion, it would break the standard for no additional benefit
  • The Bank MAY handle the authentication only and let the Bank handle the consent screen
    • This gives control over the consent screen to the Bank
    • It is less secure since now the Bank iD decides for the Bank what the SeP can do with End-User's data
    • The Bank iD would have to propagate this authorization information into the Bank, which would need to validate it

What does your Bank need to implement to be compliant?

Please see the Bank iD API endpoint overview for a detailed technical description.

Broadly speaking, as a Bank you will need to implement an OpenID Connect wrapper around your Identity Provider (IdP). This wrapper will need to conform to the Bank iD specification. It will therefore provide:

  • A Dynamic registration API - this API will allow SePs to register into your identity system
  • A Discovery API - this is a set of well-known endpoints which are there for auto configuration and URL discovery. It allows you flexibility regarding endpoint locations, encryption algorithms and more. It also allows you to easily rotate encryption keys.
  • Authorization and token exchange APIs - These are well specified OAuth2/OpenID Connect APIs which serve the core authentication
  • A Token revocation API - For RP originated logouts
  • A HealthCheck API - For liveness and outage information

Your solution will also need to have the following capabilities:

  • Call RP Logout API - The Bank will call this API when the End-User has removed their consent for a SeP in the Bank's Internet Banking
  • Download RP encryption keys; URL of these is delivered during dynamic registration
  • Encrypt and validate JSON Web Tokens (JWTs) - These enhance security and are prescribed in the OpenID Connect specification
  • Setup Mutual TLS channel to the RP
  • Properly use and verify Public Key Infrastructure (PKI) certificates

List of scopes and claims offered through Bank iD

Scopes used in Profile API

ScopeClaims included
profile.namegiven_name, family_name, middle_name
profile.titlestitle_prefix and title_suffix
profile.birthdatebirthdate, age and date_of_death
profile.birthplaceNationalitybirthplace, primary_nationality and nationalities
profile.addressestype, street, buildingapartment, streetnumber, evidencenumber, city, cityarea, zipcode, country and ruian_reference
profile.idcardstype, description, country, number, valid_to, issuer and issue_date
profile.paymentAccountspaymentAccounts, paymentAccountsDetails
profile.legalstatusmajority, pep, limited_legal_capacity
notification.claims_updatedRequest for sending notifications on the update of listed claims

Scopes used in UserInfo API

ScopeClaims included
profile.namename, given_name, family_name, middle_name, nickname and preferred_username
profile.emailemail and email_verified
profile.phonenumberphone_number and phone_number_verified
notification.claims_updatedRequest for sending notifications on the update of listed claims


Legend for Source: I - IdP internal systems, S - Government registers, C - Combined data from internal systems and government registers

namegiven_nameSGiven name of a physical person, should always be present
family_nameSFamily name of a physical person, should always be present
middle_nameSMiddle name of a physical person, seldomly used
nicknameINickname used by a physical person
preferred_usernameIPreferred username used by physical person
phonenumberphone_numberIPhone number of a physical person without spaces and with country prefix +420123456789, usually present
phone_number_verifiedIIf the number has been verified by the IdP
emailemailIE-mail of the a physical person, usually present
email_verifiedIIf the e-mail has been verified by the IdP
addressestypeIIf the address type is Permanent residence, it's from government registers. If it's contact address, it's from IdP internal systems
streetCStreet is usually present, for small villages unused
buildingapartmentCBuildingapartment is usually present, for small houses unused
streetnumberCStreetnumber is usually present, for small villages unused
evidencenumberCEvidencenumber is rarely used in suburbs
cityCCity should always be present
cityareaCCity area is usually present
zipcodeCZip code should always be present
countryCCountry should always be present
ruian_referenceCRÚIAN reference is usually present for Czech addresses
birthdatebirthdateSBirth date of the physical person, should always be present
ageIAge of a physical person derived from birthdate by IdP, should always be present
date_of_deathSDate of death of the physical person
titlestitle_prefixITitle prefix of the physical person, seldomly used
title_suffixITitle suffix of the physical person, seldomly used
gendergenderIGender of the physical person, should always be present
birthnumberbirthnumberSBirthnumber given by Czech Government, should always be present for Czech Citizens
birthplaceNationalitybirthplaceSBirthplace of a physical person, should always be present
primary_nationalityIPrimary natinality of the physical person, seldomly used
nationalitiesSA list of nationalities of the physical person, should always be present
birthcountrySBirth country of the physical person, should always be present
maritalstatusmaritalstatusIMarital status of the physical person, optional
idcardstypeSType of the document corresponding to the government registers, should always be present
descriptionIDescription of the document used by IdP, optional
countrySIssuing country of the document, should always be present
numberSNumber of the document, should always be present
valid_toSExpiration date of the document, should always be present
issuerSIssuing government body, optional
issue_dateSIssue date of the document, optional
legalstatusmajoritySLegal majorty status of the physical person, should always be present
pepIPolitically exposed person status according to Anti-money laundering laws in Czech republic, should always be present
limited_legal_capacityIStatus for people with limited legal capacity, should always be present
paymentAccountspaymentAccountsIList of payment accounts physical person has in IdP as owner, optional
paymentAccountsDetailsIList of payment accounts and currency physical person has in IdP as owner, optional
verificationtrust_frameworkIAnti-money laundering framework used by IdP's "cz_aml", should always be present
timeITime stamp in ISO 8601:2004 [ISO8601-2004] YYYY-MM-DDThh:mm[:ss]TZD format representing the date and time when the physical identity verification process took place for audit purposes, optional
verification_processIContains a company identification number of IdP, that completed the physical identity verification process, should always be present
updatedatupdated_atITime when any of the scopes provided via Bank iD was last updated. Value in seconds from 1970-01-01T0:0:0Z, should always be present
localelocaleIPreferred language of the physical person for better presentation of interface like "cs_CZ", should always be present
zoneinfozoneinfoIRepresentation of a physical person's time zone like "Europe/Prague", should always be present

Filling amr values

In order to fill correct amr values according to RFC8176, here is a guideline on how to fill them:

Type of authentizationamr values
Login, Password, SMSmfa, pwd, sms
Login, Password, Software Keymfa, pwd, swk + pin or face or fpt
Login or QR code, Software Keymfa, swk + pin or face or fpt
Certificate, PINmfa, sc, pin

Software Key is either dedicated app for authorization or combined app for authorization and mobile banking. If you cannot identify which type of biometrics is used in your Software Key, use fpt.

Filling addresses

There are several types of addresses, in order to fill it out correctly here are some examples:


Example 1

  "buildingapartment": "10",
  "city": "Libníkovice",
  "cityarea": "Borovice",
  "zipcode": "50346",
  "country": "CZ",
  "ruian_reference": "15761673"

Example 2

  "buildingapartment": "722",
  "city": "Rapotín",
  "street": "Zámecká",
  "cityarea": "Rapotín",
  "zipcode": "78814",
  "country": "CZ",
  "ruian_reference": "27885798"

Example 3

  "evidencenumber": "845",
  "city": "Brno",
  "cityarea": "Jundrov",
  "zipcode": "63700",
  "country": "CZ",
  "ruian_reference": "31179711"

Example 4

  "buildingapartment": "1491",
  "streetnumber": "13",
  "street": "Berlínská",
  "city": "Praha",
  "cityarea": "Hostivař",
  "zipcode": "10200",
  "country": "CZ",
  "ruian_reference": "26682826"

Example 5

  "evidencenumber": "194",
  "street": "Hulická",
  "city": "Praha",
  "cityarea": "Újezd nad Lesy",
  "zipcode": "19016",
  "country": "CZ",
  "ruian_reference": "22534288"

Example 6

  "evidencenumber": "2894",
  "streetnumber": "78",
  "street": "Červnová",
  "city": "Plzeň",
  "cityarea": "Litice",
  "zipcode": "32100",
  "country": "CZ",
  "ruian_reference": "28054717"

Security considerations

Due to the nature of the information provided by Bank iD, a high level of security is required.

See the Security guideline for recommended security practices when implementing the Bank iD solution.