SeP API Endpoint Overview
Version: 1.3 updated 22.11.2022
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:
{
"introspection_endpoint_auth_signing_alg_values_supported": [
"HS256",
"HS512",
"RS256",
"RS512",
"PS512",
"ES512"
],
"request_parameter_supported": false,
"authorize_endpoint": "https://oidc.sandbox.bankid.cz/auth",
"claims_parameter_supported": false,
"introspection_endpoint": "https://oidc.sandbox.bankid.cz/token-info",
"profile_endpoint": "https://oidc.sandbox.bankid.cz/profile",
"issuer": "https://oidc.sandbox.bankid.cz/",
"id_token_encryption_enc_values_supported": [
"A256GCM"
],
"userinfo_encryption_enc_values_supported": [
"A256GCM"
],
"authorization_endpoint": "https://oidc.sandbox.bankid.cz/auth",
"service_documentation": "https://developer.bankid.cz/docs",
"introspection_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_jwt",
"private_key_jwt"
],
"claims_supported": [
"addresses.buildingapartment",
"addresses.city",
"addresses.country",
"addresses.ruian_reference",
"addresses.street",
"addresses.streetnumber",
"addresses.type",
"addresses.zipcode",
"age",
"birthcountry",
"birthdate",
"birthnumber",
"birthplace",
"claims_updated",
"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"
],
"op_policy_uri": "https://developer.bankid.cz/documents/privacy-policy",
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_jwt",
"private_key_jwt"
],
"response_modes_supported": [
"query"
],
"backchannel_logout_session_supported": false,
"token_endpoint": "https://oidc.sandbox.bankid.cz/token",
"response_types_supported": [
"code",
"token"
],
"request_uri_parameter_supported": true,
"grant_types_supported": [
"authorization_code",
"implicit",
"refresh_token"
],
"ui_locales_supported": [
"cs"
],
"userinfo_endpoint": "https://oidc.sandbox.bankid.cz/userinfo",
"verification_endpoint": "https://oidc.sandbox.bankid.cz/verification",
"op_tos_uri": "https://developer.bankid.cz/documents/terms-of-use",
"ros_endpoint": "https://oidc.sandbox.bankid.cz/ros",
"require_request_uri_registration": true,
"code_challenge_methods_supported": [
"plain",
"S256"
],
"id_token_encryption_alg_values_supported": [
"RSA-OAEP",
"RSA-OAEP-256",
"ECDH-ES"
],
"frontchannel_logout_session_supported": false,
"claims_locales_supported": [
"en",
"en-US"
],
"request_object_signing_alg_values_supported": [
"PS512",
"ES512"
],
"request_object_encryption_alg_values_supported": [
"RSA-OAEP",
"RSA-OAEP-256",
"ECDH-ES"
],
"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",
"notification.claims_updated"
],
"backchannel_logout_supported": true,
"check_session_iframe": "https://oidc.sandbox.bankid.cz/session-iframe",
"acr_values_supported": [
"loa2",
"loa3"
],
"request_object_encryption_enc_values_supported": [
"A256GCM"
],
"display_values_supported": [
"page"
],
"profile_signing_alg_values_supported": [
"PS512"
],
"userinfo_signing_alg_values_supported": [
"PS512"
],
"profile_encryption_enc_values_supported": [
"A256GCM"
],
"userinfo_encryption_alg_values_supported": [
"RSA-OAEP",
"RSA-OAEP-256",
"ECDH-ES"
],
"end_session_endpoint": "https://oidc.sandbox.bankid.cz/logout",
"token_endpoint_auth_signing_alg_values_supported": [
"HS256",
"HS512",
"RS256",
"RS512",
"PS512",
"ES512"
],
"frontchannel_logout_supported": true,
"profile_encryption_alg_values_supported": [
"RSA-OAEP",
"RSA-OAEP-256",
"ECDH-ES"
],
"jwks_uri": "https://oidc.sandbox.bankid.cz/.well-known/jwks",
"subject_types_supported": [
"public",
"pairwise"
],
"id_token_signing_alg_values_supported": [
"PS512"
]
}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": [
{
"kty": "RSA",
"x5t#S256": "fYowjlnVtUVM3EvJahDnIBjZITeS2SK-9zeE4j3iZ-w",
"e": "AQAB",
"use": "enc",
"kid": "rp-encrypt",
"x5c": [
"MIIElTCCBBugAwIBAgICECwwCgYIKoZIzj0EAwMwfjELMAkGA1UEBhMCQ1oxDjAMBgNVBAgMBVByYWhhMSAwHgYDVQQKDBdCYW5rb3ZuaSBpZGVudGl0YSwgYS5zLjEdMBsGA1UEAwwUQmFua0lEIFByb2R1Y3Rpb24gQ0ExHjAcBgkqhkiG9w0BCQEWD2FkbWluQGJhbmtpZC5jejAeFw0yMTAzMTgwNzUwMDJaFw0yNDAzMTcwNzUwMDJaMFsxCzAJBgNVBAYTAkNaMQ4wDAYDVQQIDAVQcmFoYTEgMB4GA1UECgwXQmFua292bmkgaWRlbnRpdGEsIGEucy4xGjAYBgNVBAMMEUJhbmtJRCBwcm9kdWN0aW9uMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAxFLhcDDXnkdcO7CV1gjm4pXu60VFVuVKdYazZ+Bv1EXZ8I6NNQ/yrS0fysyLdaeNEwTrQ2rhb2BjuaR9aOvrPdhFlS2yKZ+k4+wkWeioc6t3jZvb9fJvKpCxozMU8XwC/OVO81G3Az5Gyv/nAGCzNmHRsXUiJBA9gh5OVduBJyAZN6w7s8F4A+QQlSdbMkVduHpUqGlGbvDDZ0zpssJQv2pA3i6y3mfAEPccr75Vgx/le9+6PC/e7BaZFUY/BdP6KmesitPZgD6EACP/QUh21jHn0feGDV+nGkZswPxZp3FCEz6YnkZg24/C6JHOjUee/gATjjjUC+uxpVPLuUGjR+Rf0WMmczMec3LJTfXwhx33ai6nQ02vp8UUGzjfSzF0UiztrWJQ9pRgc4o95h4npcLO+n7uh3NVR2/nHtBPEYGvxxZyX50Ux8HibaHEKZvoQARQ6/MTKgo0FpjGd0G97BxB5FKxw7WwiSLI9USQuDubnE3xqnQMsgJcAlg2HcQkCMu5P+6H2mer9l3wm127KFDHaZeUvV8feEBX6juz4kguQwwtZg/Op1/Hbjh/+pRvUCnbj+erjLzX4Y1rwYZlTlg3QRTaTbxV+Qhfv5gO7ZTlXSvyCIWhKnUYc8EGT1VpKDhoOdzVM23VT5m9plZKZQsyrMJMD1DP15sh2Tj1/8ECAwEAAaOB4DCB3TAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIGQDAzBglghkgBhvhCAQ0EJhYkQmFua0lEIFByb2R1Y3Rpb24gQ2xpZW50IENlcnRpZmljYXRlMB0GA1UdDgQWBBRzRJstwoejw003aJ6fquk9rsU1QDAfBgNVHSMEGDAWgBQqoi9yTXXY0beUgU8zj/QtExL35jALBgNVHQ8EBAMCBBAwOwYDVR0fBDQwMjAwoC6gLIYqaHR0cHM6Ly9jYS5iYW5raWQuY3ovY3JsL3Byb2QvcHJvZC5jcmwuY3JsMAoGCCqGSM49BAMDA2gAMGUCMQCDv5oUXSpGdQFgSD9QPzl6pqTRX2zMeFT4OPj3IKSJPrdEi7A4iPTjWs9r2dm9ngsCMEwCMeFbc3iIA6H+iZGDEgls4pOJQAn5qNq1td9VQijqw+XSeGMkwYmtV/SvRlOyyw=="
],
"n": "xFLhcDDXnkdcO7CV1gjm4pXu60VFVuVKdYazZ-Bv1EXZ8I6NNQ_yrS0fysyLdaeNEwTrQ2rhb2BjuaR9aOvrPdhFlS2yKZ-k4-wkWeioc6t3jZvb9fJvKpCxozMU8XwC_OVO81G3Az5Gyv_nAGCzNmHRsXUiJBA9gh5OVduBJyAZN6w7s8F4A-QQlSdbMkVduHpUqGlGbvDDZ0zpssJQv2pA3i6y3mfAEPccr75Vgx_le9-6PC_e7BaZFUY_BdP6KmesitPZgD6EACP_QUh21jHn0feGDV-nGkZswPxZp3FCEz6YnkZg24_C6JHOjUee_gATjjjUC-uxpVPLuUGjR-Rf0WMmczMec3LJTfXwhx33ai6nQ02vp8UUGzjfSzF0UiztrWJQ9pRgc4o95h4npcLO-n7uh3NVR2_nHtBPEYGvxxZyX50Ux8HibaHEKZvoQARQ6_MTKgo0FpjGd0G97BxB5FKxw7WwiSLI9USQuDubnE3xqnQMsgJcAlg2HcQkCMu5P-6H2mer9l3wm127KFDHaZeUvV8feEBX6juz4kguQwwtZg_Op1_Hbjh_-pRvUCnbj-erjLzX4Y1rwYZlTlg3QRTaTbxV-Qhfv5gO7ZTlXSvyCIWhKnUYc8EGT1VpKDhoOdzVM23VT5m9plZKZQsyrMJMD1DP15sh2Tj1_8E"
},
{
"kty": "EC",
"x5t#S256": "TnaGIMHLKjxvfx4EQGrXOueG9c8Fk2nlyGsTBVBK2Tw",
"use": "sig",
"crv": "P-384",
"kid": "mtls",
"x5c": [
"MIIDETCCApagAwIBAgICECowCgYIKoZIzj0EAwMwfjELMAkGA1UEBhMCQ1oxDjAMBgNVBAgMBVByYWhhMSAwHgYDVQQKDBdCYW5rb3ZuaSBpZGVudGl0YSwgYS5zLjEdMBsGA1UEAwwUQmFua0lEIFByb2R1Y3Rpb24gQ0ExHjAcBgkqhkiG9w0BCQEWD2FkbWluQGJhbmtpZC5jejAeFw0yMTAzMDQwNTA1NDdaFw0yMjAzMDQwNTA1NDdaMGExCzAJBgNVBAYTAkNaMQ4wDAYDVQQIDAVQcmFoYTEgMB4GA1UECgwXQmFua292bmkgaWRlbnRpdGEsIGEucy4xIDAeBgNVBAMMF0Jhbmtvdm5pIGlkZW50aXRhLCBhLnMuMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEG6vPecxuqTN92+g6mFqrLoov7IWt599QUQ23j7oxY4ZmBAMAz2KM7zULau/+X0SPDk9A4mx6nwOfjL4SP1ysEziu5ScLvd4O4v8ql2UA2cFxIqFcLAEpPnWYiSUN2v26o4IBAjCB/zAJBgNVHRMEAjAAMBEGCWCGSAGG+EIBAQQEAwIFoDAzBglghkgBhvhCAQ0EJhYkQmFua0lEIFByb2R1Y3Rpb24gQ2xpZW50IENlcnRpZmljYXRlMB0GA1UdDgQWBBRAQ7pl/4tw0JgPsfAYOdAB1vcAsjAfBgNVHSMEGDAWgBQqoi9yTXXY0beUgU8zj/QtExL35jAOBgNVHQ8BAf8EBAMCBeAwHQYDVR0lBBYwFAYIKwYBBQUHAwIGCCsGAQUFBwMEMDsGA1UdHwQ0MDIwMKAuoCyGKmh0dHBzOi8vY2EuYmFua2lkLmN6L2NybC9wcm9kL3Byb2QuY3JsLmNybDAKBggqhkjOPQQDAwNpADBmAjEA+zx8xKUGv3jS7JjXgxVrxX4ZxCSHd2A7GmLCp0YdS42+X0a0/xP+30nWEd0YG7o1AjEAqJHcip1H0HV3uqw+B5AtssGEH//lt+N5MZZkNWSa8WYtbOunXentBaqOfUmGRqqT"
],
"x": "G6vPecxuqTN92-g6mFqrLoov7IWt599QUQ23j7oxY4ZmBAMAz2KM7zULau_-X0SP",
"y": "Dk9A4mx6nwOfjL4SP1ysEziu5ScLvd4O4v8ql2UA2cFxIqFcLAEpPnWYiSUN2v26"
},
{
"kty": "RSA",
"x5t#S256": "VOAJMMCpfJDYdRW1uE_9_Fw8pBA1HJcqmQq_4xFRuWc",
"e": "AQAB",
"use": "sig",
"kid": "rp-sign",
"x5c": [
"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"
],
"n": "xBeRT-xgvxR40MEmJWN-9EPyRl_MxaiWoKAfCG16iM0W0lyBqdej2QKSX70rh6di3YupbNyZeD5Yij037_VPOrrdyyk2Oirw2xx1-aWS6B3T9GXD_Vmfb3k6kw6A9nl4mlDbV7MuWS_fqHldv2QTFCPxX0AQ2ohZJrJiLD3Rbm93W14tzYQUEixUh1YamrtR-iTGHSHOxdTNHqk1r_waTBh-GJiYPxNMd3BruLZrv0cHlH3NdxG-Ge37Rgg6_sI3OEp8qmVul8cazVM4nth1vWLBTeEDY2vmANfZ119vPAaAvDw1vxgI5XBDGR6QZCKF8ifx5bfA5fxEQhLfEtC_lQ"
}
]
}Authorization API
BankID Authorization flow supports various types of grants for the authentication process and obtaining access_token and id_token.
| Flow type | Description |
|---|---|
| authorization_code refresh_token | Code grant is the most common authentication flow. It allows applications to securely exchange tokens and obtain a refresh_token in case of offline access. |
| implicit | Implicit 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 type | Use | Required minimum token validity |
|---|---|---|
| access_token | Token used to authorize API requests. | 3600 seconds |
| refresh_token | Token representing offline (long-term) access. Refresh_token is used to release a new short-term access_token. | 1 year |
| id_token | This 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 method | Description |
|---|---|
| Client Secret POST | The BankID Developer portal will issue client_secret that the client application sends the request to the token endpoints. |
| Client Secret JWT | The BankID Developer portal will issue client_secret that the client application uses to sign the JWT assertion (an HMAC SHA algorithm). |
| Private Key JWT | Communication 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_id=0f8837d4-77e0-47cc-9789-c53d8ca27928
&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"
}
},
"name": "Jan Novák",
"given_name": "Jan",
"family_name": "Novák",
"gender": "male",
"birthdate": "1970-08-01",
"email": "j.novak@email.com",
"zoneinfo": "Europe/Prague",
"locale": "cs_CZ",
"phone_number": "+420123456789",
"updated_at": 1650887066
}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"
}
},
"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": 1650887066
}Sequence diagram of the Profile API call
API for a list of available banks
Exposed by the BankID. Authoritatively described in bankid_for_sep.yaml. Not authenticated.
This endpoint provides information regarding available banks and services they provide.
GET https://oidc.bankid.cz/api/v1/banks
Response 200 OK:
{
"items": [
{
"id": "297d3f16-c4c0-4f48-8d98-c94d16eb9e35",
"title": "Air Bank",
"description": null,
"available_logo_images": [
{
"id": "4cff4db9-adc4-499a-b698-c186fb14df49",
"url": "https://img.bankid.cz/GjFzHXjQhWvhEx2HFdHhnIq8bVkbA3R4XRULujuBFzo/fit/1024/1024/no/1/czM6Ly9maWxlc2VydmljZS80Y2ZmNGRiOS1hZGM0LTQ5OWEtYjY5OC1jMTg2ZmIxNGRmNDkucG5n",
"width": 1025,
"height": 1025
}
],
"available_services": [
"AUTHENTICATION",
"SIGN_SINGLE_PDF",
"SIGN_SO"
]
},
{
"id": "3b42a926-7d02-472b-bd22-f12fdf22bf0f",
"title": "Komerční banka",
"description": "Komerční banka",
"available_logo_images": [
{
"id": "1686e019-6909-4849-95d3-37fdb981bb13",
"url": "https://img.bankid.cz/as1e3iLVdcQUCXQA996ho5qL736sLKKKitiKkRkVxEQ/fit/1024/1024/no/1/czM6Ly9maWxlc2VydmljZS8xNjg2ZTAxOS02OTA5LTQ4NDktOTVkMy0zN2ZkYjk4MWJiMTMucG5n",
"width": 1024,
"height": 1024
}
],
"available_services": [
"AUTHENTICATION",
"SIGN_SINGLE_PDF",
"SIGN_SO",
"NOTIFICATION"
]
},
{
"id": "bd86df8c-56a0-4d0b-b7f6-bcff83fa09de",
"title": "MONETA",
"description": null,
"available_logo_images": [
{
"id": "5702ae1a-8517-4fb8-a79d-61682e1b839b",
"url": "https://img.bankid.cz/xpdBzR8AM9r_xBPG3vw3228l6hKGpLb9r6D6HXTzLNo/fit/1024/1024/no/1/czM6Ly9maWxlc2VydmljZS81NzAyYWUxYS04NTE3LTRmYjgtYTc5ZC02MTY4MmUxYjgzOWIucG5n",
"width": 1024,
"height": 1024
}
],
"available_services": [
"AUTHENTICATION",
"SIGN_SINGLE_PDF",
"SIGN_SO",
"NOTIFICATION"
]
},
{
"id": "032051de-f43d-4cb8-a911-2ef03773a3b4",
"title": "ČSOB a.s.",
"description": null,
"available_logo_images": [
{
"id": "0c13079d-e293-4fe3-b792-08a30e74e30d",
"url": "https://img.bankid.cz/wal-WnJrnnLyq_dpXOKz86XA24LGBlmlDzqjzD3anXo/fit/1024/1024/no/1/czM6Ly9maWxlc2VydmljZS8wYzEzMDc5ZC1lMjkzLTRmZTMtYjc5Mi0wOGEzMGU3NGUzMGQucG5n",
"width": 1024,
"height": 1024
}
],
"available_services": [
"NOTIFICATION",
"AUTHENTICATION",
"SIGN_SINGLE_PDF"
]
},
{
"id": "7e623fed-8aab-4d24-9918-c610d3057859",
"title": "Česká spořitelna",
"description": "CSAS",
"available_logo_images": [
{
"id": "5ad1f28e-3ef1-48e1-bfcb-1f8efab01982",
"url": "https://img.bankid.cz/ec8G2pLQK8dTfCYzj_8hsa3gk61Kv2ieb7sfmwWQMhc/fit/2477/2477/no/1/czM6Ly9maWxlc2VydmljZS81YWQxZjI4ZS0zZWYxLTQ4ZTEtYmZjYi0xZjhlZmFiMDE5ODIucG5n",
"width": 2477,
"height": 2477
}
],
"available_services": [
"AUTHENTICATION",
"SIGN_SINGLE_PDF",
"NOTIFICATION",
"SIGN_SO"
]
}
]
}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": [
"phone_number"
]
}
]
}