Security

Keeping clients’ data and assets safe is key to ČSOB.

Endpoint URI

The APIs are available under https://api.csob.cz/. The exact location is documented in each service’s details. For instance the GetToken service listens at https://api.csob.cz/api/csob/oauth2/v1/token.

Transport mechanisms

All APIs are exposed as RESTful services accessible via the HTTP protocol with TLS. JSON format is typically used to transfer data.

Mutual TLS authentication

So far, all communication with the API resources needs to be secured by both the server and also client certificates. This makes sure that only licensed parties that can prove their identity and the licensed scopes can access these APIs.

Suported client certificates:

• PSD2 certificate
• CSOB private certificate

The sender MUST send a complete, ordered chain of certificates, starting with the client's certificate proper, then a certificate for the intermediate CA that issued it, then a certificate for the intermediate CA that issued the previous intermediate CA certificate, and so on. At the end of the chain, the root CA certificate must be included.

For chain certificates related to PSD2 certificate ask your PSD2 certificate issuer. Chain certificates related to CSOB private certificate can be found here:

• csob-customer-ca.cer
• csob-customer-root-ca.cer

API keys

Each application that wants to use APIs, have to be registered in Developer Portal (follow the the registration procedure so that you get your API key). You need to specify the API key value in the apikey HTTP header in requests you are sending to most of the API resources.

Authorization

When making requests to access the bank clients data or make transactions on their behalf, the clients need to authorize such calls.

To prove that a bank client gave a consent to access their accounts data or make transactions on their behalf, CSOB APIs use the OAuth 2.0 authorization. At this moment we support the Authorization Code Grant. Requests to most of the resources of our APIs need to contain the Authorization HTTP header with a valid OAuth bearer access token proving that the bank client has approved you to make the request.

There is also a set of an additional services:

• Registration and Authorization services that allow third parties to register their applications and obtain all authorization data needed to use the APIs.
• User info service obtaining claims about the authenticated End-User

The application authorization by end-user (bank client)

When making requests to access the bank clients data or make transactions on their behalf, the clients need to authorize such calls. This is achieved by your application directing the bank client to a ČSOB consent page where the client securely logs in to the bank and authorizes your application to perform the requested operation. The consent page will show the user information about your application you provided in the registration call including the application logo.

https://identita.csob.cz/mep/fs/fl/oauth2/auth?state=state123&redirect_uri=https%3A%2F%2Ffinadvisor.domain.com%2Fauth-redirect&client_id=TP100141&response_type=code&scope=AISP&access_type=offline

The parameters you pass in the query:

• client_id: the ID that was issued when you registered your application
• redirect_uri: the URI (URL-encoded) where the user should be redirected once he or she authorizes your application to act on their behalf; it must be on of the URIs you specified when you registered the application
• response_type: specify code in order to get the authorization code grant
• scope: the PSD2 scope(s) the application needs
• state: an optional arbitrary string that will be returned back to your application so that you can limit security threats
• access_type: an optional string flag which drives which token types will be returned. If the parameter is not provided, “online” value is default.
  • online - access token only
  • offline - access token and refresh token

Once your application is successfully granted the permissions by the client, the bank redirects (HTTP 302) the client back to the redirect_uri with an authorization code in the query parameter and if you specified, also with the optional state you can use to verify that the user was redirected back to your application with the authorization code by a real ČSOB server:

https://finadvisor.domain.com/auth-redirect?code=2%2FCOigoxESgm5NIvaYEGG68a5O?state=state123

Error handling

The APIs follow REST principles, therefore when an operation succeeds, an HTTP status code from the 2xx family will be returned; in case of error, 4xx for client errors or 5xx for a server error will be returned.

Additionally to the HTTP status code, error responses contain a payload with more information of why the operation has failed.

Error payloads

For OAuth2 related errors, we follow the conventional application/json type structure:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
   "error":"invalid_redirect_uri",
   "error_description":"The value of the redirect URI is invalid."
}

It respects the following JSON schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",
   "type":"object",
   "properties":{
      "error":{
         "description":"Error code",
         "type":"string"
      },
      "error_description":{
         "description":"Error description",
         "type":"string"
      }
   },
   "required":[
      "error"
   ],
   "additionalProperties":false
}

Common errors

Below are listed errors that can occur when invoking any of the APIs. API-specific errors are documented in the relevant API documentations.