Digital Toolkit

Authentication - Authorization Code (Command Line)

Admin API > Quickstarts > Authentication - Authorization Code (Command Line)

The Admin API uses OpenID Connect and OAuth 2.0 for authentication.

This Quickstart guides you through making your first Authorization Code flow authentication using the command line.

This example assumes that you have a working familiarity with the cURL command line tool.


Before you get started, you’ll need to get the following from the back office administrator at your financial institution who has access to Users & Groups.

  • External Applications with API Credentials
  • Configured Redirect URI (OAuth Debugger is a great option if you just want to test quickly.)

If the administrator does not know where to do this, they can review the Configuration topic.

Understanding Your Development Experience
Are you a financial institution?

If you are a financial institution or working directly with a financial institution, you should work with the back office administrator at your institution to get appropriate access to the Admin API.

Are you a fintech or independent developer?

If you are a fintech or other developer working without a financial institution, you are likely using the JackHenry.Dev developer portal. In this case, you will not have access to the Banno Back Office.

API credentials

You’ll need API credentials to exercise the authorization flow. The External Application you create will have a client_id and client_secret that you will use.

Configured Redirect URI

You’ll need to have a Redirect URI configured in your External Application. This is where the user’s browser will be redirected after the user has granted authorization.

Secure Redirect URIs

Redirect URIs must use HTTPS except in local development. HTTPS is required for all production redirect URIs to properly secure the connection between your application and our API.

The only exception is for local development. The following is a list of local options which are included in the HTTP allowlist:

  • Host names of localhost or those that end in .local
  • Any address in the IPv4 range of,,, or (which includes

Software requirements


If you don’t have the curl command line tool installed on your system already, you’ll need to install a version that is appropriate for your operating system.

Concept: Understanding the code_challenge and code_verifier parameters

The Proof Key for Code Exchange extension adds additional security to the OAuth2 authorization code flow. The requesting app creates a secret (code_verifier) and submits a hash of that secret on the initial auth request. The secret itself is then submitted as part of the token exchange and ensures that the server exchanging the token is the same one that requested the authorization code.

Generating correct code_verifier and code_challenge values from the command line is difficult. It’s recommended to use an OAuth client that supports PKCE.

Best Practices for code_verifiers

The code_verifier is an important security mechanism in the OAuth 2.0 Authorization Code flow. We specifically use the code_verifier as part of the Proof Key for Code Exchange (PKCE) to prevent code interception attacks.

Here are some best practices to consider around code_verifier usage:

  • Generate a new, cryptographically random, code_verifier for every authorization request. Never reuse them across requests.
  • After completing the token exchange, clear the code_verifier from your application. Do not persist it.
  • If your authorization flow is interrupted, regenerate the code_verifier rather than reusing.

Generating a code verifier

A client simply needs to generate a random string of characters. The string must be at least 43 bytes long and no more than 128 bytes. It must be composed of only the following characters:

  • English letters A-Z or a-z
  • Numbers 0-9
  • Symbols “-”, “.”, “_” or “~”.

Creating the code challenge

The code challenge is created by generating a SHA-256 byte hash of the code verifier. The result is then base64url-encoded.

Example code verifier and code challenge creation

NodeJS example
const crypto = require('crypto');
const codeVerifier = crypto
  .slice(0, 128);
const codeChallenge = crypto
  .replace(/=/g, '')
  .replace(/\+/g, '-')
  .replace(/\//g, '_');

To check your work, use this code_verifier and ensure you get the listed code_challenge:

Valid output

Check your work: Paste in a verifier or hit the create button to generate one.


Step 1. Get authorization from the user

Send the user to the authorization URL

The URL will be of the form:



  • CLIENT_ID is the client_id from your API credentials.
  • REDIRECT_URI is the configured Redirect URI where the browser will be redirected after authorization is granted.
  • SCOPES is one or more . The openid scope is required to initiate an OpenID Connect request. To see all currently supported scopes, navigate to Admin API OpenID Configuration.
  • STATE is an opaque, non-guessable value generated by the client to prevent Cross-site request forgery (CSRF) attacks. This enables the client to verify the validity of the request.
  • CODE_CHALLENGE is the PKCE code challenge value.

Get the authorization code from the redirect

The redirect will be of the form:

Redirect URL Form


  • REDIRECT_URI is the configured Redirect URI.
  • CODE is an authorization code that can be exchanged for an access token.
  • STATE is the client-generated value passed in to the authorization URL.

Step 2. Exchange the authorization code for an access token

Request using curl

Use curl to make an HTTP POST request of the form:

Curl token post
curl -v --request POST \
  --url \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data client_id=[CLIENT_ID] \
  --data client_secret=[CLIENT_SECRET] \
  --data grant_type=authorization_code \
  --data 'code=[CODE]' \
  --data redirect_uri=[REDIRECT_URI] \
  --data code_verifier=[CODE_VERIFIER]


  • CLIENT_ID is the client_id.
  • CLIENT_SECRET is the client_secret from your API credentials.
  • CODE is the authorization code from the previous step.
  • REDIRECT_URI is the configured Redirect URI.
  • CODE_VERIFIER is the PKCE code verifier value.

Authentication response

The authentication server will respond with a JSON payload of the form:

Token Response
  "access_token": "<lengthy-json-web-token-string>",
  "expires_at": "<ISO date format>",
  "id_token": "<lengthy-json-web-token-string>",
  "scope": "openid",
  "token_type": "Bearer"


  • access_token is the access token in JWT (JSON Web Token) format.
  • expires_at an ISO date format expiration
  • id_token is the identity token in JWT (JSON Web Token) format.
  • scope is the set of scopes authorized by the user.
  • token_type is the type of token (the string “Bearer”).

Next steps

Congratulations! Continue your learning journey:

Have a Question?
Have a how-to question? Seeing a weird error? Get help on StackOverflow.
Register for the Digital Toolkit Meetup where we answer technical Q&A from the audience.
Last updated Tue Nov 7 2023