Token handling via API

The tokens you generate with the secret credentials you obtained in the Open Banking platform are used company-wide. It means that each of the access tokens you generate and use allows access to all of the accounts you have or will connect through your company.

Glossary

• Access token: a unique string of characters used in token-based authentication to allow an application to access an API. An access token contains the security credentials for a login session and identifies the user, the user's groups, the user's privileges, and, in some cases, a particular application.
• Refresh token: a unique string serving as credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires or to obtain additional access tokens with an identical or narrower scope.
• Client ID: a unique user identifier issued by GoCardless.
• User secret: a secret known only to your application and the authorization server. It protects your resources by only granting tokens to authorized requestors. Protect your user secrets and never include them in mobile or browser-based apps.
• Token pair: access and refresh tokens together.

Follow these steps to make sure that you are handling your tokens correctly.

Step 1. Generate secret credentials

1. Head to the user secrets section in Open Banking Platform
2. Create new user secrets
3. Store secret ID and secret key in the environment of your app or other secure location and make sure not to push it in Git

Neither other users nor admin users of your company account are able to see other users' secret credentials.

Step 2. Get access token

Using your secret credentials, make the following request:

In response, you will receive the following fields:

An access token is valid for 24 hours, while a refresh token is valid for 30 days.

Step 3. Use your access token

Provide your access token in the Authorization header as in the following example:

Step 4. Refresh your token

After 24 hours, when your access token has expired, you have to refresh it, by making the following request:

In response you will get a new access token, which will be valid for 24 hours:

Remember: the refresh token expires in 30 days. When the refresh token has expired, you will need to obtain a new pair of access/refresh tokens.

Please, do not request a new access token for each request to the API. This is not necessary, and the requests for obtaining access/refresh tokens will be rate-limited in the nearest future.

Step 5. Obtain new token pair

After 30 days, when the refresh token has expired and you cannot use it to refresh your access token, you have to obtain new token pair using your secret credentials as described in Step 1.

How to revoke access?

There are multiple ways to withdraw existing access: 

• Delete a user
  • After a user is deleted, you can still generate a pair of access & refresh tokens with their secret credentials, but it is not possible to make any requests with the created tokens. 
• Delete a pair of secret credentials
  • After the secret credentials are deleted, it is not possible to generate new access & refresh tokens. 
  • The existing refresh token related to the deleted secret credentials is immediately black-listed. 
  • The existing access token related to the deleted secret credentials will still be active until its expiration time (less than 24 hours).

•