SeP API Endpoint Overview

Version: 1.1

The following endpoints are provided by BankID for consumption by the Service Provider. Each of these endpoints only contains illustratory examples. Please see the referenced OpenAPI documents for a full authoritative description of these resources.

OpenID Configuration Discovery API

Exposed by the BankID. Authoritatively described in bankid_for_sep.yaml. Not authenticated.

This endpoint provides information about OpenID Connect configuration.

GET https://oidc.sandbox.bankid.cz/.well-known/openid-configuration

Response 200 OK:

{
  "request_parameter_supported": false,
  "claims_parameter_supported": false,
  "introspection_endpoint": "https://oidc.sandbox.bankid.cz/token-info",
  "profile_endpoint": "https://oidc.sandbox.bankid.cz/profile",
  "scopes_supported": [
    "openid",
    "offline_access",
    "profile.addresses",
    "profile.birthdate",
    "profile.birthnumber",
    "profile.birthplaceNationality",
    "profile.email",
    "profile.gender",
    "profile.idcards",
    "profile.legalstatus",
    "profile.locale",
    "profile.maritalstatus",
    "profile.name",
    "profile.paymentAccounts",
    "profile.phonenumber",
    "profile.titles",
    "profile.updatedat",
    "profile.zoneinfo",
    "profile.verification"
  ],
  "issuer": "https://oidc.sandbox.bankid.cz/",
  "acr_values_supported": [
    "loa2",
    "loa3"
  ],
  "userinfo_encryption_enc_values_supported": [
    "A256GCM"
  ],
  "id_token_encryption_enc_values_supported": [
    "A256GCM"
  ],
  "authorization_endpoint": "https://oidc.sandbox.bankid.cz/auth",
  "service_documentation": "https://oidc.sandbox.bankid.cz/about",
  "request_object_encryption_enc_values_supported": [
    "A256GCM"
  ],
  "device_authorization_endpoint": "https://oidc.sandbox.bankid.cz/devicecode",
  "userinfo_signing_alg_values_supported": [
    "ES512",
    "PS512"
  ],
  "claims_supported": [
    "addresses.buildingapartment",
    "addresses.city",
    "addresses.country",
    "addresses.ruian_reference",
    "addresses.street",
    "addresses.streetnumber",
    "addresses.type",
    "addresses.zipcode",
    "age",
    "birthdate",
    "birthnumber",
    "birthplace",
    "date_of_death",
    "email",
    "email_verified",
    "family_name",
    "gender",
    "given_name",
    "idcards.country",
    "idcards.description",
    "idcards.issue_date",
    "idcards.issuer",
    "idcards.number",
    "idcards.type",
    "idcards.valid_to",
    "limited_legal_capacity",
    "locale",
    "majority",
    "maritalstatus",
    "middle_name",
    "name",
    "nationalities",
    "nickname",
    "paymentAccounts",
    "pep",
    "phone_number",
    "phone_number_verified",
    "preferred_username",
    "primary_nationality",
    "sub",
    "title_prefix",
    "title_suffix",
    "txn",
    "updated_at",
    "verified_claims.verification",
    "zoneinfo"
  ],
  "claim_types_supported": [
    "normal"
  ],
  "op_policy_uri": "https://oidc.sandbox.bankid.cz/about",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_jwt",
    "private_key_jwt"
  ],
  "response_modes_supported": [
    "query"
  ],
  "token_endpoint": "https://oidc.sandbox.bankid.cz/token",
  "response_types_supported": [
    "code",
    "token"
  ],
  "request_uri_parameter_supported": true,
  "userinfo_encryption_alg_values_supported": [
    "RSA-OAEP-256"
  ],
  "grant_types_supported": [
    "authorization_code",
    "implicit",
    "refresh_token"
  ],
  "end_session_endpoint": "https://oidc.sandbox.bankid.cz/logout",
  "userinfo_endpoint": "https://oidc.sandbox.bankid.cz/userinfo",
  "token_endpoint_auth_signing_alg_values_supported": [
    "ES512",
    "PS512"
  ],
  "op_tos_uri": "https://oidc.sandbox.bankid.cz/about",
  "require_request_uri_registration": true,
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ],
  "id_token_encryption_alg_values_supported": [
    "RSA-OAEP-256"
  ],
  "jwks_uri": "https://oidc.sandbox.bankid.cz/.well-known/jwks",
  "subject_types_supported": [
    "public",
    "pairwise"
  ],
  "id_token_signing_alg_values_supported": [
    "ES512",
    "PS512",
    "none"
  ],
  "request_object_signing_alg_values_supported": [
    "ES512",
    "PS512"
  ],
  "request_object_encryption_alg_values_supported": [
    "RSA-OAEP-256"
  ]
}

JWK Keys Discovery API

Exposed by the BankID. Authoritatively described in bankid_for_sep.yaml. Not authenticated.

This endpoint returns JSON Web Keys to be used as public keys for verifying OIDC ID Tokens and responses, as well as for encrypting requests.

GET https://oidc.sandbox.bankid.cz/.well-known/jwks

Response 200 OK:

{
  "keys": [
    {
      "alg": "RS256",
      "kid": "1603dfe0af8f4596",
      "key_ops": [
        "sign",
        "verify"
      ],
      "use": "sig",
      "kty": "RSA",
      "x5c": "MIICUDCCAbmgAwIBAgIBADANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJjejEOMAwGA1UECAwFUHJhaGExEDAOBgNVBAoMB0V4YW1wbGUxFDASBgNVBAMMC2V4YW1wbGUuY29tMB4XDTIwMDExNjE2NDExOFoXDTIxMDExNTE2NDExOFowRTELMAkGA1UEBhMCY3oxDjAMBgNVBAgMBVByYWhhMRAwDgYDVQQKDAdFeGFtcGxlMRQwEgYDVQQDDAtleGFtcGxlLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEArOEYBRyBhcd6u3phrbU2xvTaBoy6W14CpqqfsBrfsUsuSB+JELBCj3a+zRIvy4EY9cnQbF7cPNxbXdCbGEokAUjIIuVBk/I6XhKRe01vlax82o+eFfIhUfl7Xb2Bx9U3m98Qbt3WNrv+VYJjjFP8HWSsWCHKCazj+yvozjuFXUsCAwEAAaNQME4wHQYDVR0OBBYEFN5SUrsStd4aLhBs+MWGRDxLeUP4MB8GA1UdIwQYMBaAFN5SUrsStd4aLhBs+MWGRDxLeUP4MAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQELBQADgYEAL59fE6itiRrck6Z7RCjwnOnebQJxpoB/L7TUC/aUIXss40mCviBVKD+Hl4+3sGyp4J2LlzzqhFcPgR9NyxQt0bkahJGH0UXvZETJe719UA0kGFrPMdt6ujwB6/rafT6TinzXN0lEEGikersTrh3BR9Hjw+v7nCQ0D5RfuDn6s5s="
    }
  ]
}

Authorization API

BankID Authorization flow supports various types of grants for the authentication process and obtaining access_token and id_token.

Flow typeDescription
authorization_code refresh_tokenCode grant is the most common authentication flow. It allows applications to securely exchange tokens and obtain a refresh_token in case of offline access.
implicitImplicit flow is suitable in those cases where it is impossible to communicate through back-end solutions/servers.

Diagram with example of code grant flow

The sequence diagram shows the course of the authentication flow with the exchange of code for tokens. In the case of offline access, the chart is supplemented by an example of exchanging a refresh token for an access token.

Diagram with example of implicit flow

The sequence diagram shows the acquisition of a token via the implicit flow. The diagram also shows the acquisition of a token from the IDP, which in any case takes place in the code grant flow mode.

BankID recommends considering the use of the implicit flow approach, especially from a security perspective!

Authorization GET endpoint is a starting point for OAuth2 and OpenID Connect authorization flows. This request authenticates the user and returns tokens to the client application as a part of the callback response.

This endpoint is exposed by the BankID. Authoritatively described in bankid_for_sep.yaml.

GET or POST https://oidc.sandbox.bankid.cz/auth

Auth request example

GET /auth?
  redirect_uri=https://serviceprovider.cz/callback
  &client_id=589b7c53-c0bf-4f6d-8fee-c6972c5d88bf
  &response_type=code
  &scope=openid%20profile.name%20profile.gender%20offline_access
  &state=main002
Host: bankid.cz

Scope openid is required! In the context of its use, it is specified that the authorization flow control will be a process established by the OpenID standard (e.g., including the issuing of id_token).

The scope offline_access should be specified whenever the application, based on the authentication flow, requires the release of not only access_token but also refresh_token. For such a case, the application must have registered code grant flow and refresh_token grant (in its settings on the BankID Developer Portal).

Response redirection:

Auth success response

HTTP/1.1 302 Found
Location: https://serviceprovider.cz/callback?
  code=6a72a932a67cf859570a8fb986dcefce19c844995d30fe1ad32d1e5af5579eb2
  &state=main002

Error redirection:

Auth error response

HTTP/1.1 302 Found
Location: https://serviceprovider.cz/callback?
    error=unauthorized_client
    &state=main002

Tokens used in the BankID solution

Tokens

Token typeUseRequired minimum token validity
access_tokenToken used to authorize API requests.3600 seconds
refresh_tokenToken representing offline (long-term) access. Refresh_token is used to release a new short-term access_token.1 year
id_tokenThis token was identifying the end-user within the current context and session.At least as long as access_token (3600 seconds)

Access Token

The access_token is the main result of the authentication process. This token is used to call user-centric APIs (primarily /userinfo and /profile). In the case of BankID, it may be an unsigned stateless token. The access_token hash can be specified as one of the id_token claims (specifically at_hash claim), which is issued simultaneously with the access_token to ensure integrity.

This token's validity can be found directly at issue in response (authorization_code and refresh_token grant flow) to the API /token or call the API /token-info. The response to the call /token MUST also include a list of scopes for the issued token.

Refresh Token

Refresh_token is used to issue a new access_token, for example, if the access_token expires. Refresh_token is issued if the application requesting its release has a refresh_token grant configured at the Developer Portal and if the application asked for an offline_access scope in the authentication request

The scope of this token's context corresponds to the result of the authentication at which it was issued. When exchanging refresh_token for access_token, the application can request the same or smaller range of scopes.

ID Token

The id_token represents the identification of the end-user and is issued together with the access_token. The id_token is always signed and contains information about the time of issue and validity of the token. In the case of BankID, it always contains the end-user identifier as a claim sub.

The id_token is issued signed by the issuer's key, and the application must verify this signature in each case.

Token exchange API

The token endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token.

Supported endpoint token authorization methods (the developer can select the required authorization method in the application settings in the Developer Portal):

Token endpoint auth methodDescription
Client Secret POSTThe BankID Developer portal will issue client_secret that the client application sends the request to the token endpoints.
Client Secret JWTThe BankID Developer portal will issue client_secret that the client application uses to sign the JWT assertion (an HMAC SHA algorithm).
Private Key JWTCommunication takes place via signed JWT client_assertion objects in requests. For this type of authorization, the client application must issue its public JWK keys.

Exposed by the BankID. Authoritatively described in bankid_for_sep.yaml. Uses client credentials for authentication.

POST https://oidc.sandbox.bankid.cz/token

Authorization code exchange request:

POST /token HTTP/1.1
Host: bankid.cz
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=DuorPn4S4ypn5cxH9u0DGo
&client_id=0f8837d4-77e0-47cc-9789-c53d8ca27928
&client_secret=AJFfp_BKiyzsSAY1rDYgE5mR_KPovQgnvBRKLc18yIqeuFd-jRR5h3wuGxiOioYBjKl5NYEXGT25n-NaMJU2AEU
&redirect_uri=https://serviceprovider.cz/callback

Authorization code exchange response 200 OK:

{
  "access_token": "c03e997c-aa96-4b3f-ad0c-98626833145d",
  "token_type": "Bearer",
  "refresh_token": "1f703f5f-75da-4b58-a1b0-e315700e4227",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Refresh token exchange request:

POST /token HTTP/1.1
Host: bankid.cz
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&scope=openid%20profile.name%20profile.addresses%20offline_access
&refresh_token=1f703f5f-75da-4b58-a1b0-e315700e4227
&redirect_uri=https://serviceprovider.cz/callback
&client_secret=368b8099c14c0964a4a9f958c8b5786c46845ec1

Refresh token exchange response 200 OK:

{
  "access_token": "c03e997c-aa96-4b3f-ad0c-98626833145d",
  "token_type": "Bearer",
  "expires_in": 6000,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response 400 Request invalid:

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

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter"
}

TokenInfo API

The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON representing the meta information surrounding the token, including whether this token is currently active.

Exposed by the BankID. Authoritatively described in bankid_for_sep.yaml. Uses client credentials or a client access token for authentication.

POST https://oidc.sandbox.bankid.cz/token-info

Request example:

POST /token-info HTTP/1.1
Host: oidc.sanbox.bankid.cz
Content-Type: application/x-www-form-urlencoded

token=WwVEraxkI7KbtP31wD3XSpZKqGpsLiXg
&token_type_hint=refresh_token

Response 200 OK:

{
  "active": true,
  "scope": "openid profile.addresses",
  "client_id": "d1bdc32e-1b06-4609-9f60-073685267f88",
  "token_type": "access_token",
  "exp": 1419356238,
  "iat": 1419350238,
  "sub": "25657805-66d4-4707-980a-f12429f17592",
  "aud": "https://rp.example.com/resource",
  "iss": "https://bankid.cz/"
}

Logout API

Exposed by the BankID. Authoritatively described in bankid_for_sep.yaml. Not authenticated.

SeP redirect the User-Agent of the End-User to this EP whenever it wishes to logout and forget a session. On completion, the End-User is redirected to post_logout_redirect_uri

POST https://oidc.sandbox.bankid.cz/logout

Request example:

POST /logout HTTP/1.1
Host: bankid.cz
Content-Type: application/x-www-form-urlencoded

id_token_hint=eyJhbGciOiJSUzI1NiIsImtpZCI6IjdlOGFkZmMzMjU1OTEyNzI0ZDY4NWZmYmIwOThjNDEyIiwidHlwIjoiSldUIn0
&post_logout_redirect_uri=https://serviceprovider.cz/logout
&session_state=3cf56e5d-40b0-45b5-a329-8c27741947

Response 200 OK

Session logout successful

User info API

The UserInfo and Profile API are the basic interfaces for retrieving authenticated user data. The range of user-approved scopes strictly controls the range of data. A detailed list of scopes and their associated claims is available in the API technical documentation bankid-for-sep.yaml.

UserInfo endpoint is intended primarily for frequently performed identification and authentication, such as repeated login processes to the system/application. This endpoint's data range corresponds to the data ranges for logins using social network identities (Google, LinkedIn).

Access is authorized using a valid end-user access_token that was obtained from a completed login flow.

GET https://oidc.sandbox.bankid.cz/userinfo

Request example:

GET /userinfo HTTP/1.1
Host: oidc.sandbox.bankid.cz
Accept: application/json
Authorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwi

Response 200 OK (application/json):

{
  "sub": "23f1ac00-5d54-4169-a288-794ae2ead0c4",
  "txn": "6941683f-c6ee-410c-add0-d52d63091069:openid:profile.name:profile.gender",
  "verified_claims": {
    "verification": {
      "trust_framework": "cz_aml",
      "verification_process": "45244782"
    },
    "claims": {
      "given_name": "Jan",
      "family_name": "Novák",
      "gender": "male",
      "birthdate": "1970-08-01"
    }
  },
  "name": "Jan Novák",
  "given_name": "Jan",
  "family_name": "Novák",
  "gender": "male",
  "birthdate": "1970-08-01",
  "nickname": "Fantomas",
  "preferred_username": "JanN",
  "email": "j.novak@email.com",
  "email_verified": false,
  "zoneinfo": "Europe/Prague",
  "locale": "cs_CZ",
  "phone_number": "+420123456789",
  "phone_number_verified": true,
  "updated_at": 1568188433000
}

Sequence diagram of the Userinfo API call

Profile API

Unlike UserInfo, the Profile API is designed primarily to perform KYC or AML client authentication. This corresponds to a much more extensive range of data provided. A complete overview of claims and scopes is in the detailed API documentation bankid-for-sep.yaml.

Access is authorized using a valid end-user access_token that was obtained from a completed login flow.

GET https://oidc.sandbox.bankid.cz/profile

Request example:

GET /profile HTTP/1.1
Host: oidc.sandbox.bankid.cz
Accept: application/json
Authorization: Bearer eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwi

Response 200 OK (application/json):

{
  "sub": "23f1ac00-5d54-4169-a288-794ae2ead0c4",
  "txn": "6941683f-c6ee-410c-add0-d52d63091069:openid:profile.name:profile.addresses",
  "verified_claims": {
    "verification": {
      "trust_framework": "cz_aml",
      "verification_process": "45244782"
    },
    "claims": {
      "given_name": "Jan",
      "family_name": "Novák",
      "gender": "male",
      "birthdate": "1970-08-01",
      "addresses": [
        {
          "type": "PERMANENT_RESIDENCE",
          "street": "Olbrachtova",
          "buildingapartment": "1929",
          "streetnumber": "62",
          "city": "Praha",
          "zipcode": "14000",
          "country": "CZ"
        }
      ],
      "idcards": [
        {
          "type": "ID",
          "description": "Občanský průkaz",
          "country": "CZ",
          "number": "123456789",
          "valid_to": "2023-10-11",
          "issuer": "Úřad městské části Praha 4",
          "issue_date": "2020-01-28"
        }
      ]
    }
  },
  "given_name": "Jan",
  "family_name": "Novák",
  "gender": "male",
  "birthdate": "1970-08-01",
  "birthnumber": "7008010147",
  "age": 50,
  "majority": true,
  "date_of_death": null,
  "birthplace": "Praha 4",
  "primary_nationality": "CZ",
  "nationalities": [
    "CZ",
    "AT",
    "SK"
  ],
  "maritalstatus": "MARRIED",
  "email": "J.novak@email.com",
  "phone_number": "+420123456789",
  "pep": false,
  "limited_legal_capacity": false,
  "addresses": [
    {
      "type": "PERMANENT_RESIDENCE",
      "street": "Olbrachtova",
      "buildingapartment": "1929",
      "streetnumber": "62",
      "city": "Praha",
      "zipcode": "14000",
      "country": "CZ",
      "ruian_reference": "14458921"
    }
  ],
  "idcards": [
    {
      "type": "ID",
      "description": "Občanský průkaz",
      "country": "CZ",
      "number": "123456789",
      "valid_to": "2023-10-11",
      "issuer": "Úřad městské části Praha 4",
      "issue_date": "2020-01-28"
    }
  ],
  "paymentAccounts": [
    "CZ0708000000001019382023"
  ],
  "updated_at": 1568188433000
}

Sequence diagram of the Profile API call

SeP API endpoint overview

The following endpoints are to be made available to the BankID by the SeP. Each of these endpoints only contains illustratory examples. Please see the referenced OpenAPI documents for a full authoritative description of these resources.

Back-Channel Logout API

Logout endpoint specified in OpenID.BackChannelLogout.

Exposed by SeP. Authoritatively described in sep_for_bankid.yaml. Not authenticated.

POST /back-channel/logout

Request example:

POST /back-channel/logout HTTP/1.1
Host: serviceprovider.cz
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Logout token JWT body example:

{
  "iss": "https://bankid.cz",
  "sub": "f232e6dc-c8b7-4454-8acc-9f07a267ffde",
  "aud": "d8b47d81318a86454babd47572d57252",
  "iat": 1605296323,
  "jti": "687cdd8e-25e7-11eb-adc1-0242ac120002",
  "sid": "4a4e93aa-5d06-4036-bdfa-eb8350bc44d6",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  }
}

Front-Channel Logout API

Logout endpoint specified in OpenID.FrontChannel. Rendered in an IFrame.

Exposed by SeP. Authoritatively described in sep_for_bankid.yaml. Not authenticated.

GET /front-channel/logout

Request example:

GET /front-channel/logout?
  iss=https%3A%2F%2Fbankid.cz
  &sid=db96bfbf-a11a-4dd8-a89d-94cd1a411ea6
Host: serviceprovider.cz

Notification API

Batch notification endpoint which accepts a list of notification tokens. These are mainly claim update notifications.

Exposed by SeP. Authoritatively described in sep_for_bankid.yaml. Not authenticated.

POST /notify

Request example:

POST /notify HTTP/1.1
Host: serviceprovider.cz
Content-Type: application/x-www-form-urlencoded

notification_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Notification token JWT:

{
  "iss": "https://idp.example.com",
  "iat": "1582797458",
  "jti": "913CC0F7-27BA-40D9-9F4F-8DF74AC3596B",
  "events": [
    {
      "type": "claim_updated",
      "original_event_at": "2020-06-15T14:16:32",
      "sub": "9456B875-62D3-4533-A502-E05D39936F3A",
      "affected_client_ids": [
        "F932FF05-E04C-4CD1-86E4-CE82F1F51EFB"
      ],
      "affected_claims": [
        "profile.phone_number"
      ]
    }
  ]
}

Cookies are bad for your teeth but good for BankID • Cookie policy