High Level Overview for Service Providers

Version: 1.2 updated on 14.06.2022

This document provides a bird's-eye overview of the Bank iD system, its technical goals, decisions and related motivations. This document SHOULD also provide a starting point for Bank implementors 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.

How to read this document

The CAPITALIZED words throughout these guidelines have a special meaning as defined in RFC2119:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Bank iD system actors

  • Bank - An entity which provides authentication and KYC services.
  • End-User - A person 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 credentials 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.

Identity Providers supported by Bank iD

The list is continuously updated.

Legend: Y - Supports, N - Not currently supported.

From what age is a bank identity issued15718151515151515
Service SIGN (sign one PDF)YYYYYYYYY
Service SIGN (sign multiple PDF)NYYYYYYYY
Service SIGN (sign object)YYYYYYYYY
Ability to use Bank iD by disponentsNYYYYYYYY
Ability to use Bank iD for foreigners with idcards with MRZ issued in CZYYYYYYYYY
Ability to use Bank iD for foreigners with idcards without MRZ issued in CZNYNNYYYNN

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.

List of scopes and claims offered through Bank iD

Scopes used in KYC - 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, city, zipcode, country and ruian_reference
profile.idcardstype, description, country, number, valid_to, issuer and issue_date
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 verified_email
profile.phonenumberphone_number and phone_number_verified
notification.claims_updatedRequest for sending notifications on the update of listed claims

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.

UX considerations

To use the buttons and texts associated with Bank iD, it is necessary to follow the style guide and UX guide lines. Bank iD allows customization of the IdP selection page in the SeP environment. All documents are in our UX manual.

End-user identification

Unique end-user identification

The system for unique identifier is not currently running.

Sector Identifier URI usage

Bank iD uses pairwise subject identifiers, therefore each end user will have a unique sub (subject) identifier for each Service Provider, based on a Sector Identifier. The Sector Identifier is the host component (domain) of the Sector Identifier URI. If no Sector Identifier URI is provided, the Sector Identifier is the host component (domain) of the registered Redirect URI. If there are multiple hostnames in Redirect URIs, you are required to provide a Sector Identifier URI.

If you wish to have consistent sub identifiers across multiple apps with distinct hostnames in Redirect URIs, you can use a common Sector Identifier URI to unify the Sector Identifier of the apps. This Sector Identifier URI must point to an endpoint returning a JSON array of all Redirect URIs used in all apps which use this Sector Identifier URI. This URI along with JSON file has to be accessible from our portal.

Example: I want to have matching sub identifiers in App1 (Redirect URI https://app1.123.com/callback) and App2 (Redirect URI https://app2.123.com/callback). I will set Sector Identifier URI to https://example.com/sector.json in both apps. sector.json will contain the following JSON:


Front and back channel logout

Both logout modes are supported as specified in the OpenID.FrontChannel and OpenID.BackChannel documents.

SLA service

Implementation guide for marking requests with a unique identifier and levering SLA offer.

Unique identifier for organization

If your company has requested SLA offering and business matters were settled, in your organization and linked applications will have in configuration special field for unique organization identifier. If this is present in http headers of your request or if that's not possible as request param in URL. This identifier must not be shared with other organizations and in case of infringements, Bank iD will suspend SLA offering until issue is resolved.

We assume that this identifier will be reused in future for other services if needed.

Technical details for implementation

For API endpoints (/ros, /token, /.well-known/*, /profile, /userinfo, ...) following header MUST be included in HTTP headers under header X-Sep-identifier. Example:

POST /token HTTP/1.1
Host: bankid.cz
Content-Type: application/x-www-form-urlencoded
X-Sep-identifier: f8ba33de-4ca8-4a11-a251-867cd3e3b41b


For redirected endpoints (/auth) identifier MUST be included as another parameter in URL Example:

GET /auth?
Host: bankid.cz