Digital Toolkit

Client Credentials Flow

Admin API > Overview > Authentication > Client Credentials Flow

The Admin API uses the OAuth Client Credentials flow to obtain an Access Token. An External Application can use its credentials to directly obtain an Access Token.

Once the Access Token expires, the External Application requests a new one when necessary.

The Client Credentials flow requires authenticating with a signed JSON Web Token (JWT) that uses a public key + private key pair.

Obtaining an access token

Using the Client Credentials flow requires authenticating to the /token endpoint with a signed JWT that has been signed using a public + private key pair.

Public key + private key

See the Public Key + Private Key topic.


See the Configuration topic.

Signed JWT

Authenticating to the /token endpoint requires the developer to create a signed JWT with the following properties:

  • jti – a unique id used as a nonce to prevent replay attacks
  • aud – this must be the exact URL of the /token endpoint
  • sub – the Client ID of the application
  • iss – the Client ID of the application
  • exp – the timestamp (in milliseconds) when the JWT is no longer valid (do not set the expiration value to more than 5 minutes from now)

Example JWT payload

Example JWT Payload
  "jti": "bfbaaa5b-aa91-45d0-aba2-999d57f08500",
  "aud": "",
  "sub": "199e6f35-4e9a-482e-b980-b10308aa428a",
  "iss": "199e6f35-4e9a-482e-b980-b10308aa428a",
  "exp": 1606396546977

The JWT must be signed with the Private Key. The following algorithms are supported:

  1. ES256 - ECDSA using P-256 and SHA-256
  2. PS256 - RSASSA-PSS using SHA-256 with MGF1 with SHA-256
  3. RS256 - RSASSA-PKCS1-v1_5 using SHA-256

Example of a properly signed JWT

Example Signed JWT

Token request

Using a properly signed JWT, make an HTTP POST request to the endpoint.

The HTTP POST should use a content-type of application/x-www-form-urlencoded.

The HTTP POST request body must include the following parameters:

  • client_assertion – this value is the signed JWT
  • client_assertion_type – the string urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • grant_type – the string client_credentials
  • scope – the string openid

The parameters in the request body should be properly encoded.

Token Response
A successful token request will have a response with a JSON payload containing an Access Token.

Access token usage and lifetime

The Authentication Framework - Tokens article has information on the various Tokens.

Command line utility

The @jack-henry/banno-client-creds-helper command line utility is available via npm.

The @jack-henry/banno-client-creds-helper demonstrates the Client Credentials flow and can be used to obtain an Access Token.

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 Mar 26 2024