Authorization (OAuth 2)

To call most of the APIs, you have to follow an authorization process based on OAuth2 protocol.

This process verifies both the third-party application and the end-user / customer. It is also set up in a way that customer credentials are not stored within the third-party application infrastructure. They are provided by the customer directly to the bank, thus not only guaranteeing actual security, but also providing the assurance of its existance to all sides. 

oAuth access_code flow

This is achieved by following three steps.

  • Call the provided Authorization URL (as noted in the security section of the API definition).  A SAMPLE Authentication URL is in the form :

https://{oauth_base_url}/authorize?response_type=code&client_id=APPLICATION_ID&redirect_uri=APPLICATION_REDIRECT_URI&scope=API_SCOPE, where :

1. APPLICATION_ID is the id that was provided durring application registration.
2. APPLICATION_REDIRECT_URI is a link that you have to provide when you register the application. This link will be called (with redirection) via a code that will be produced at the end of this call in case of a successfull loginAPI.
3. API_SCOPE represents the level of access granted to backend APIs and has specific values, depending on the environment (DEVELOPMENT / PRODUCTION) and the product family of the called API (PB APIs v1.1, PB APIs v1.2, PSD2 APIs)

The result of this call is a code required for the next step.

  • Call the provided Token URL. A SAMPLE Token URL is in the form: 


The parameters needed should be passed in the body, while the Content-Type should be set to application/x-www-form-urlencoded. The request parameters are:

1. grant_type is either authorization_code or refresh_tokendepending on whether an initial access token or a refresh token is requested
2. client_id is the application id, the same passed later in the x-ibm-client-id header when calling the rest of the APIs
3. client_secret is the application secret, saved during application creation.
4. code is the value returned from theprevious call to the Authorization URL.  This code expires quickly, so the Token URL should be called immediately after
5. redirect_uri is the url declared during application creation, where the API should redirect after completion of the OAuth process

This call returns an access token, required for all APIs requesting to access user information. 

  •  Call an API. The previous access token is passed in the Authorization header in the form "Bearer <token>", where "token" is the access token.  More details are provided in the "API Calls" section.

The ACTUAL Authorization and Token URLs are available in each API's specification, provided in the section API Products. The table below includes the OAuth Authorization and Token URLs, as well as the respective scopes, for each API Product family (PB APIs v1.1, PB APIs v1.2, PSD2 APIs) and each environment (DEVELOPMENT, PRODUCTION).

  Authorization URL Token URL Scope

PB APIs v.1.1 (DEVELOPMENT - SANDBOX) /sandboxapi
PB APIs v.1.2 (DEVELOPMENT - SANDBOX) /sandboxapi
sandboxapi (generic sandbox access to all resources)
offline_access (required for refresh tokens)

winbankAccess (read access to resources)

winbankAccess.monetaryTransactions (access to perform monetary transfers)

winbankAccess (read access to resources)
winbankAccess.monetaryTransactions (access to perform monetary transfers)
offline_access (required for refresh tokens)



If the application you want to implement is not a web application, and you cannot provide a redirect url to be called, there is a technical solution to get the intermediate code.  In a desktop application, a web control must be used to initiate the authorization proccess, and a dummy redirect url.  When the user provides his/her credentials and authorizes your application for access, this control will try to redirect to the dummy redirect url, which will contain the code as a parameter.  This is the parameter you need to capture, in order to use it for the token call (second step).