Refresh Tokens

In this guide, we will walk through these scenarios:

• How to request a Refresh Token
• How to exchange a Refresh Token for a new Access Token

This is useful when you have an Access Token which has expired and you need to regain authorized access via a new Access Token.

Prerequisites

To be successful, you will first need to understand how authentication works. Take a look at the Authentication (Command Line) Quickstart for a walkthrough of how to authenticate.

Requesting a Refresh Token

The authentication system will issue a Refresh Token if you include the scope https://api.banno.com/consumer/auth/offline_access as part of the initial authentication request.

That scope is what tells the authentication system to issue a Refresh Token as part of the authentication flow.

For more information on scopes, see the Authentication Framework - OpenID Connect and OAuth 2.0 documentation.

Requests

Modifying the authentication (command line) quickstart

In the first step “Step 1. Get Authorization from the user”, you’ll need to add this as one of the SCOPES values: https://api.banno.com/consumer/auth/offline_access

After you complete the second step “Step 2. Exchange the Authorization Code for an Access Token”, the Refresh Token will be in the response.

Response

{
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 600,
  "id_token": "<lengthy-json-web-token-string>",
  "refresh_token": "<refresh-token-string>",
  "scope": "openid https://api.banno.com/consumer/auth/offline_access",
  "token_type": "Bearer"
}

• access_token is the access token in JWT (JSON Web Token) format.
• expires_in is the amount of time (in seconds) for which the access token is valid.
• id_token is the identity token in JWT (JSON Web Token) format.
• refresh_token is the Refresh Token.
• scope is the set of scopes authorized by the user.
• token_type is the type of token (the string “Bearer”).

Exchanging a Refresh Token for a new Access Token

Requests

POST /oidc/token

curl -v --request POST \
  --url https://[CONSUMER_API_ENVIRONMENT]/a/consumer/api/v0/oidc/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data refresh_token=[REFRESH_TOKEN] \
  --data client_id=[CLIENT_ID] \
  --data client_secret=[CLIENT_SECRET]

• CONSUMER_API_ENVIRONMENT is specific to your financial institution and matches with Banno Online for your institution.
• REFRESH_TOKEN is your Refresh Token.
• CLIENT_ID is the Client ID from your API credentials.
• CLIENT_SECRET is the Client Secret from your API credentials.

Response

{
  "access_token": "<lengthy-json-web-token-string>",
  "expires_in": 600,
  "id_token": "<lengthy-json-web-token-string>",
  "refresh_token": "<refresh-token-string>",
  "scope": "openid https://api.banno.com/consumer/auth/offline_access",
  "token_type": "Bearer"
}

• access_token is the access token in JWT (JSON Web Token) format.
• expires_in is the amount of time (in seconds) for which the access token is valid.
• id_token is the identity token in JWT (JSON Web Token) format.
• refresh_token is a newly-issued Refresh Token.
• scope is the set of scopes authorized by the user.
• token_type is the type of token (the string “Bearer”).

Next steps

Take a look at specific documentation in the API Reference.

Review concepts in the Authentication Framework - Tokens documentation.

Learn about scopes in the Authentication Framework - OpenID Connect and OAuth 2.0 documentation.