Token management

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.

 

The Tokens API provides you with services to obtain or invalidate OAuth access and refresh tokens that are necessary to call the PSD2 services themselves.

Get token

POST /api/csob/psd2/oauth2/token

This resource serves two purposes:

  1. Obtain an OAuth access_token and refresh_token pair from an authorization code you received once the user gave your application consent to access their data or perform operations on their behalf
  2. Get a new access_token from a valid refresh_token

Note: The returning parameters (access_token and/or refresh_token) depends on the value of access_type request parameter during the end-user application authorization. For detailed description look at documentation pages The application authorization by end-user

We start by listing characteristics common to both use-cases. Specific request and response samples for the two variants are mentioned further in the text.

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.

Response schema

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "access_token" : {
      "description": "The access token issued by the authorization server.",
      "type": "string"
    },
    "token_type": {
      "description": "The type of the issued token (Bearer).",
      "type": "string"
    },
    "expires_in": {
      "description": "The lifetime in seconds of the access token.",
      "type": "integer"
    },
    "refresh_token": {
      "description": "The refresh token issued by the authorization server.",
      "type": "string"
    },
    "scope": {
      "description": "The scope for the allowed PSD2 services.",
      "type": "string"
    },
    "acr": {
      "description": "Signifies a security level according to ISO 29115. Value of 0 means nonSCA.",
      "type": "string"
    }
  },
  "required":["access_token", "token_type"]
}

Get OAuth tokens from authorization code

Once the bank client authorized your application to access their data, the bank authorization server will redirect the user back to your application and will provide you with an OAuth authorization code grant type which you will exchange for an access and refresh tokens.

The request contains the following parameters in its body with Content-Type: application/x-www-form-urlencoded:

  • grant_type: in this scenario the value must be authorization_code
  • code: the authorization code
  • client_id: identification of the registered application
  • client_secret: the secret you receive for the application during the registration step
  • redirect_uri: one of the redirect URIs you specified during the application registration step

Sample request

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

grant_type=authorization_code
&code=2%2FCOigoxESgm5NIvaYEGG68a5O
&client_id=TP100060
&client_secret=oiMgRRb8wZzDmhbmPQ7bqX3FtnRDMrVj
&redirect_uri=https%3A%2F%2Fmojeid.int.csob.cz%2F
cURL
curl -X POST \
  https://api.csob.cz/api/csob/psd2/oauth2/token \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=2%2FCOigoxESgm5NIvaYEGG68a5O&client_id=TP100060&client_secret=oiMgRRb8wZzDmhbmPQ7bqX3FtnRDMrVj&redirect_uri=https%3A%2F%2Fmojeid.int.csob.cz%2F'

Sample response

HTTP/1.1 200 OK

{
   "redirectUri": null,
   "refresh_token": "1/jfW4DmmFFKoyybn7XlXXxCQP1oftGoWHLp9nc1Fa1w9Bv9VW5BxEWnqp784C2Uoh",
   "access_token": "3/LSNXm1tXISLOSxJ0C7hsAV8hZiS9Rd5DCTY74XyQmnjxJzyIX3kLhX7lwhKaalGo",
   "token_type": "bearer",
   "expires_in": 3599,
   "scope": "AISP"
}

Get a new access_token

At a certain time, for security reasons, the access_token will expire and you will need to ask for a new one using a valid refresh_token.

The request contains the following parameters in its body with Content-Type: application/x-www-form-urlencoded:

  • grant_type: in this scenario the value must be refresh_token
  • refresh_token: a valid refresh_token value
  • client_id: identification of the registered application
  • client_secret: the secret you receive for the application during the registration step

Sample request

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

grant_type=refresh_token
&refresh_token=1%2FEX9wDCYz3njyCFqST8LfZx6Bic1d5UQoLtxYCtw6Q4pgIFQkZmn7Oj4nfjlaIRIp
&client_id=TP100060
&client_secret=oiMgRRb8wZzDmhbmPQ7bqX3FtnRDMrVj
cURL
curl -X POST \
  https://api.csob.cz/api/csob/psd2/oauth2/token \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&refresh_token=1%2FEX9wDCYz3njyCFqST8LfZx6Bic1d5UQoLtxYCtw6Q4pgIFQkZmn7Oj4nfjlaIRIp&client_id=TP100060&client_secret=oiMgRRb8wZzDmhbmPQ7bqX3FtnRDMrVj'

Sample response

HTTP/1.1 200 OK

{
   "redirectUri": null,
   "refresh_token": "1/jfW4DmmFFKoyybn7XlXXxCQP1oftGoWHLp9nc1Fa1w9Bv9VW5BxEWnqp784C2Uoh",
   "access_token": "3/LSNXm1tXISLOSxJ0C7hsAV8hZiS9Rd5DCTY74XyQmnjxJzyIX3kLhX7lwhKaalGo",
   "token_type": "bearer",
   "expires_in": 3599,
   "scope": "AISP"
}

Revoke token

POST /api/csob/psd2/oauth2/revoke

When you suspect that an access or refresh token issued for your application has been compromised or you want to revoke them for any other reason, use this service.

The request contains one parameter in its body with Content-Type: application/x-www-form-urlencoded:

  • token: contains a value of an access_token or refresh_token you want to invalidate

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
401 invalid_grant The provided authorization grant (e.g. authorization code, resource owner credentials or refresh token) is invalid, expired or revoked.

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/revoke HTTP/1.1
Host: api.csob.cz
APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

token=1%2FEX9wDCYz3njyCFqST8LfZx6Bic1d5UQoLtxYCtw6Q4pgIFQkZmn7Oj4nfjlaIRIp

cURL

curl -X POST \
  https://api.csob.cz/api/csob/psd2/oauth2/revoke \
  -H 'APIKEY: l7xxca45406f0e934f7eb5df07d150a38e7b' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=1%2FEX9wDCYz3njyCFqST8LfZx6Bic1d5UQoLtxYCtw6Q4pgIFQkZmn7Oj4nfjlaIRIp'

Sample response

HTTP/1.1 200 OK