Application management

API Deprecation

Notice: API Deprecation The following APIs are replaced by newer version. The new version supports except PSD2 certificates also CSOB private certificate. From PSD2 implementation point of view, there are no changes in APIs parameters only the URL endpoints are changed. Old URLs: https://api.csob.cz/api/csob/psd2/oauth2/… New URLs: https://api.csob.cz/api/csob/oauth2/v1/…

For detailed description look at documentation pages OAuth2 APIs and Third-party Management APIs.

 

Use the Applications API to register and manage your applications.

Services in this area conform to the OAuth 2.0 standard, therefore an application you are going to develop and register is called a client in the OAuth 2.0 terminology.

Register client

POST /api/csob/psd2/oauth2/register

When you are creating a new application, you should register it first in the Developer Portal to get its API key. The next step is to register the application via this call.

Request security requirements

Feature Required
Certificate ✔
API key header ✔
Access token header ✘

Supported features

Feature Supported
Paging ✘
Sorting ✘
Filtering ✘

Operation-specific errors

HTTP status code Error Description
400 invalid_redirect_uri The value of the redirect URI is invalid

Please refer to the Overview section for the error response data structure and a list of errors common to all operations.

Request schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "application": {
      "type": "object",
      "properties": {
        "application_type": {
          "description": "Type of the application. Only web or native values are allowed.",
          "type": "string",
          "enum": [
            "web",
            "native"
          ]
        },
        "redirect_uris": {
          "description": "Array of redirect URLs, where the flow is directed after a successful authorization flow",
          "type":"array",
          "items": {
            "type":"string"
          }
        },
        "client_name": {
          "description": "Name of the third party application in the Czech language.",
          "type": "string"
        },
        "client_name#en-US": {
          "description": "Name of the third party application in the English language.",
          "type": "string"
        },
        "logo": {
          "description": "Base64 encoded PNG of third party application logo.",
          "type": "string"
        },
        "contact": {
          "description": "The contact e-mail address of a responsible person for the third party application.",
          "type": "string"
        },
        "scopes": {
          "description": "List of required third party application scopes",
          "type":"array",
          "items": {
            "type":"string",
            "enum": [
              "AISP",
              "PISP",
              "CISP"
            ]
          }
        }
      },
      "required":["application_type", "redirect_uris", "client_name"]
    }
  },
  "allOf":[
    {
      "$ref": "#/definitions/application"
    }
  ]
}

Sample request

HTTP

POST /api/csob/psd2/oauth2/register HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Cache-Control: no-cache

{
    "application_type": "web",
    "client_name": "FinRadce",
    "client_name#en-US": "FinAdvisor",
    "contact": "contact@domain.com",
    "logo": "... Base64 encoded image ...",
    "redirect_uris": [
        "https://finadvisor.domain.com/auth-redirect"
    ],
    "scopes": [
        "AISP",
        "PISP"
    ]
}

cURL

curl -X POST \
  https://api.csob.cz/api/csob/psd2/oauth2/register \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "application_type": "web",
    "client_name": "FinRadce",
    "client_name#en-US": "FinAdvisor",
    "contact": "contact@domain.com",
    "logo": "... Base64 encoded image ...",
    "redirect_uris": [
        "https://finadvisor.domain.com/auth-redirect"
    ],
    "scopes": [
        "AISP",
        "PISP"
    ]
}'

Response schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "application": {
      "type": "object",
      "properties": {
        "application_type": {
          "description": "Type of the application. Only web or native values are allowed.",
          "type": "string",
          "enum": [
            "web",
            "native"
          ]
        },
        "redirect_uris": {
          "description": "Array of redirect URLs, where the flow is directed after a successful authorization flow",
          "type":"array",
          "items": {
            "type":"string"
          }
        },
        "client_name": {
          "description": "Name of the third party application in the Czech language.",
          "type": "string"
        },
        "client_name#en-US": {
          "description": "Name of the third party application in the English language.",
          "type": "string"
        },
        "logo": {
          "description": "Base64 encoded PNG of the third party application logo.",
          "type": "string"
        },
        "contact": {
          "description": "The contact e-mail address of a responsible person for the third party application.",
          "type": "string"
        },
        "scopes": {
          "description": "List of required third party application scopes",
          "type":"array",
          "items": {
            "type":"string",
            "enum": [
              "AISP",
              "PISP",
              "CISP"
            ]
          }
        }
      },
      "required":["application_type", "redirect_uris", "client_name"]
    }
  },
  "allOf":[
    {
      "$ref": "#/definitions/application"
    },
    {
      "properties": {
        "client_id": {
          "description": "The ID of the third party application.",
          "type": "string"
        },
        "client_secret": {
          "description": "A secret issued by the bank for the third party application.",
          "type": "string"
        },
        "client_secret_expires_at": {
          "description": "The lifetime in seconds of the client secret.",
          "type": "integer"
        },
        "api_key": {
          "description": "Value of the API key issued by a bank to the third party application. If the API key is not supported by the bank, value NOT_PROVIDED is returned.",
          "type": "string"
        }
      },
      "required": ["client_id", "client_secret"]
    }
  ]
}

Sample response

HTTP/1.1 200 OK

{
    "api_key": "NOT_PROVIDED",
    "application_type": "web",
    "client_secret_expires_at": 0,
    "client_name": "FinRadce",
    "client_name#en-US": "FinAdvisor",
    "contact": "contact@domain.com",
    "logo": "... Base64 encoded image ...",
    "client_secret": "fNRF9KUFh3BuiuoIkIzfsy91Zgr8IzJy",
    "redirect_uris": [
        "https://finadvisor.domain.com/auth-redirect"
    ],
    "scopes": [
        "AISP",
        "CISP"
    ],
    "client_id": "TP100141"
}

Get client info

GET /api/csob/psd2/oauth2/register/{client_id}

Get information about a registered client (application).

Request URI parameters

  • client_id: identification of the application; the value was returned by the application registration call

Request security requirements

Feature Required
Certificate ✔
API key header ✔
Access token header ✘

Supported features

Feature Supported
Paging ✘
Sorting ✘
Filtering ✘

Operation-specific errors

HTTP status code Error Description
401 invalid_client Invalid client_id

Please refer to the Overview section for the error response data structure and a list of errors common to all operations.

Sample request

HTTP

GET /api/csob/psd2/oauth2/register/TP100060 HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Cache-Control: no-cache

cURL

curl -X GET \
  https://api.csob.cz/api/csob/psd2/oauth2/register/TP100060 \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Cache-Control: no-cache'

Response schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "application": {
      "type": "object",
      "properties": {
        "application_type": {
          "description": "Type of the application. Only web or native values are allowed.",
          "type": "string",
          "enum": [
            "web",
            "native"
          ]
        },
        "redirect_uris": {
          "description": "Array of redirect URLs, where the flow is directed after a successful authorization flow",
          "type":"array",
          "items": {
            "type":"string"
          }
        },
        "client_name": {
          "description": "Name of the third party application in the Czech language.",
          "type": "string"
        },
        "client_name#en-US": {
          "description": "Name of the third party application in the English language.",
          "type": "string"
        },
        "logo": {
          "description": "Base64 encoded PNG of the third party application logo.",
          "type": "string"
        },
        "contact": {
          "description": "The contact e-mail address of a responsible person for the third party application.",
          "type": "string"
        },
        "scopes": {
          "description": "List of required third party application scopes",
          "type":"array",
          "items": {
            "type":"string",
            "enum": [
              "AISP",
              "PISP",
              "CISP"
            ]
          }
        }
      },
      "required":["application_type", "redirect_uris", "client_name"]
    }
  },
  "allOf":[
    {
      "$ref": "#/definitions/application"
    },
    {
      "properties": {
        "client_id": {
          "description": "The ID of the third party application.",
          "type": "string"
        },
        "client_secret": {
          "description": "A secret issued by the bank for the third party application.",
          "type": "string"
        },
        "client_secret_expires_at": {
          "description": "The lifetime in seconds of the client secret.",
          "type": "integer"
        },
        "api_key": {
          "description": "Value of the API key issued by a bank to the third party application. If the API key is not supported by the bank, value NOT_PROVIDED is returned.",
          "type": "string"
        }
      },
      "required": ["client_id", "client_secret"]
    }
  ]
}

Sample response

HTTP/1.1 200 OK

{
   "api_key":"NOT_PROVIDED",
   "application_type":"web",
   "client_secret_expires_at":0,
   "client_name":"FinRadce",
   "client_name#en-US":"FinAdvisor",
   "contact":"contact@domain.com",
   "logo":"... Base64 encoded image ...",
   "client_secret":"Cs7HBUD1OsqxVZ7u57NPlAxUAFvhaS4g",
   "redirect_uris":[
      "https://finadvisor.domain.com/auth-redirect"
   ],
   "scopes":[
      "AISP",
      "PISP"
   ],
   "client_id":"TP100060"
}

Update client

PUT /api/csob/psd2/oauth2/register/{client_id}

Update information of a registered client (application).

Request URI parameters

  • client_id: identification of the application; the value was returned by the application registration call

Request security requirements

Feature Required
Certificate ✔
API key header ✔
Access token header ✘

Supported features

Feature Supported
Paging ✘
Sorting ✘
Filtering ✘

Operation-specific errors

HTTP status code Error Description
400 invalid_redirect_uri The value of the redirect URI is invalid
401 invalid_client Invalid client_id

Please refer to the Overview section for the error response data structure and a list of errors common to all operations.

Request schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "application": {
      "type": "object",
      "properties": {
        "application_type": {
          "description": "Type of the application. Only web or native values are allowed.",
          "type": "string",
          "enum": [
            "web",
            "native"
          ]
        },
        "redirect_uris": {
          "description": "Array of redirect URLs, where the flow is directed after a successful authorization flow",
          "type":"array",
          "items": {
            "type":"string"
          }
        },
        "client_name": {
          "description": "Name of the third party application in the Czech language.",
          "type": "string"
        },
        "client_name#en-US": {
          "description": "Name of the third party application in the English language.",
          "type": "string"
        },
        "logo": {
          "description": "Base64 encoded PNG of the third party application logo.",
          "type": "string"
        },
        "contact": {
          "description": "The contact e-mail address of a responsible person for the third party application.",
          "type": "string"
        },
        "scopes": {
          "description": "List of required third party application scopes",
          "type":"array",
          "items": {
            "type":"string",
            "enum": [
              "AISP",
              "PISP",
              "CISP"
            ]
          }
        }
      },
      "required":["application_type", "redirect_uris", "client_name"]
    }
  },
  "allOf":[
    {
      "$ref": "#/definitions/application"
    }
  ]
}

Sample request

HTTP

PUT /api/csob/psd2/oauth2/register/TP100060 HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/json
Accept: application/json
Cache-Control: no-cache

{
    "application_type": "web",
    "client_name": "FinRadce",
    "client_name#en-US": "FinAdvisor",
    "contact": "contact@domain.com",
    "logo": "... Base64 encoded image ...",
    "redirect_uris": [
        "https://finadvisor.domain.com/auth-redirect"
    ],
    "scopes": [
        "CISP",
        "AISP"
    ]
}

cURL

curl -X PUT \
  https://api.csob.cz/api/csob/psd2/oauth2/register/TP100060 \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "application_type": "web",
    "client_name": "FinRadce",
    "client_name#en-US": "FinAdvisor",
    "contact": "contact@domain.com",
    "logo": "... Base64 encoded image ...",
    "redirect_uris": [
        "https://finadvisor.domain.com/auth-redirect"
    ],
    "scopes": [
        "CISP",
        "AISP"
    ]
}'

Response schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "application": {
      "type": "object",
      "properties": {
        "application_type": {
          "description": "Type of the application. Only web or native values are allowed.",
          "type": "string",
          "enum": [
            "web",
            "native"
          ]
        },
        "redirect_uris": {
          "description": "Array of redirect URLs, where the flow is directed after a successful authorization flow",
          "type":"array",
          "items": {
            "type":"string"
          }
        },
        "client_name": {
          "description": "Name of the third party application in the Czech language.",
          "type": "string"
        },
        "client_name#en-US": {
          "description": "Name of the third party application in the English language.",
          "type": "string"
        },
        "logo": {
          "description": "Base64 encoded PNG of the third party application logo.",
          "type": "string"
        },
        "contact": {
          "description": "The contact e-mail address of a responsible person for the third party application.",
          "type": "string"
        },
        "scopes": {
          "description": "List of required third party application scopes",
          "type":"array",
          "items": {
            "type":"string",
            "enum": [
              "AISP",
              "PISP",
              "CISP"
            ]
          }
        }
      },
      "required":["application_type", "redirect_uris", "client_name"]
    }
  },
  "allOf":[
    {
      "$ref": "#/definitions/application"
    },
    {
      "properties": {
        "client_id": {
          "description": "The ID of the third party application.",
          "type": "string"
        }
      },
      "required": ["client_id"]
    }
  ]
}

Sample response

HTTP/1.1 200 OK

{
  "application_type": "web",
  "client_name": "FinRadce",
  "client_name#en-US": "FinAdvisor",
  "contact": "contact@domain.com",
  "logo": "... Base64 encoded image ...",
  "redirect_uris": [
    "https://finadvisor.domain.com/auth-redirect"
  ],
  "scopes": [
    "CISP",
    "AISP"
  ],
  "client_id": "TP100141"
}

Delete client

DELETE /api/csob/psd2/oauth2/register/{client_id}

Delete a client (application).

Note that the application still exists in the Developer Portal and to clean it up completely, you should also remove it there.

Request URI parameters

  • client_id: identification of the application; the value was returned by the application registration call

Request security requirements

Feature Required
Certificate ✔
API key header ✔
Access token header ✘

Supported features

Feature Supported
Paging ✘
Sorting ✘
Filtering ✘

Operation-specific errors

HTTP status code Error Description
401 invalid_client Invalid client_id

Please refer to the Overview section for the error response data structure and a list of errors common to all operations.

Sample request

HTTP

DELETE /api/csob/psd2/oauth2/register/TP10006011 HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

cURL

curl -X DELETE \
  https://api.csob.cz/api/csob/psd2/oauth2/register/TP10006011 \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded'

Sample response

HTTP/1.1 200 OK

Renew client secret

POST /api/csob/psd2/oauth2/register/{client_id}/renewSecret

Request a new client_secret. The previous client_secret will be discarded.

Request URI parameters

  • client_id: identification of the application; the value was returned by the application registration call

Request security requirements

Feature Required
Certificate ✔
API key header ✔
Access token header ✘

Supported features

Feature Supported
Paging ✘
Sorting ✘
Filtering ✘

Operation-specific errors

HTTP status code Error Description
401 invalid_client Invalid client_id

Please refer to the Overview section for the error response data structure and a list of errors common to all operations.

Sample request

HTTP

POST /api/csob/psd2/oauth2/register/TP100060/renewSecret HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Accept: application/json
Cache-Control: no-cache

cURL

curl -X POST \
  https://api.csob.cz/api/csob/psd2/oauth2/register/TP100060/renewSecret \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Accept: application/json' \
  -H 'Cache-Control: no-cache'

Response schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "client_id": {
      "type": "string",
      "description": "The provided *client_id*"
    },
    "client_secret": {
      "type": "string",
      "description": "The newly generated *client_secret*"
    },
    "client_secret_expires_at": {
      "type": "integer",
      "title": "The Client_secret_expires_at Schema",
      "default": 0,
      "description": "Seconds since 1970-01-01T0:0:0Z determining when the *client_secret* expires. If zero or not present, the *client_secret* does not expire."
    }
  },
  "required": ["client_id", "client_secret"]
}

Sample response

HTTP/1.1 200 OK

{
   "client_id":"TP100060",
   "client_secret":"BBjkk45sd78ad454gddd8712_4555g5g5g5gg",
   "client_secret_expires_at":0
}