Access controls

clock 4-minute read calender updated Oct. 28, 2025

When being entitled isn't a bad thing

KeyBank sets up account entitlements to authenticate your identity and define the authorization rules for the APIs you need to access. These entitlements include API keys, access tokens, and KeyBank-assigned parameters.

 

Authentication and authorization are terms in the developer world that sound similar and are sometimes used interchangeably, but each has its distinct meaning. It is possible to authenticate an API that you are not authorized to use.

  • Authentication is the process of verifying the identity of a user or application attempting to access an API (like your API keys).
  • Authorization determines which APIs an authenticated user or application is allowed to access (like your access token).

API keys

An API key is a string of alpha-numeric characters that identify the user account making the call. The API keys grant you authorization to use the APIs. Without a valid API key, a call will not complete because the server only recognizes authorized users. KeyBank provides API keys for both application and client credentials. Secure application and client credentials are needed for the Non-Production test environment and the Production environment.

Application credentials

  • consumer_key: The API key to access KeyBank APIs.
  • consumer_secret: The password used with the consumer key to grant authorization to the client's resources from KeyBank.

Client credentials

  • client_id: A public hex string that identifies your application provided for each environment.
  • client_secret: A private string known only by the application and the server. this is the application's own password. Always use the client ID together with the client secret to keep the application secure.

To authorize API calls, KeyBank requires an OAuth 2.0 access token. Before requesting a token, you must be fully onboarded as a KeyBank partner. For onboarding details, refer to the Get Started Guide.

Before you start, it is helpful to know where your certificates are stored and have your KeyBank credentials ready. 

  1. Copy the cURL template. Replace all placeholders {{xxxx}} with your actual information.
  2. Add your certificate details.
    1. client.crt: Path to your certificate signing request (CSR) file. Accepted file formats include *.pem, *.crt, or *.cer.
    2. client.key: Path to your certificate’s private key file.
    3. ca.crt: Path to your certificate authority (CA) certificate.
  3. Specify the host URL for the KeyBank environment. and append scope=rs-read.
  4. Convert your application credentials (consumer_key and consumer_secret) to Base64 using a trusted tool.
  5. For the Authorization header, enter 'Basic' for basic authentication followed by your encrypted application credentials.
  6. For Id header, include your client credentials (client_id and client_secret) from KeyBank followed by grant_type=client_credentials.
  7. Send the request.

cURL command template

copylink
curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \
  ‘{{host}}/oauth/v1/token?scope=rs-read'
  -H 'Authorization: Basic {{base64 encoded consumer key and secret}}'
  -H 'Content-type: application/x-www-form-urlencoded'
  -H 'Accept: application/json'
  -d 'Id={{client id}}&Key={{client password}}&grant_type=client_credentials'

 

Response fields

  • access_token: Use this token in the Authorization header for secure mTLS API calls. It is valid for 24 hours. If expired, use the refresh token to obtain a new one. If you are unable to retrieve an access token, reassess your setup, review your API keys, and make sure you are properly connected to the environment before you try again.
  • api_product_list: Lists the API products you are authorized to use. Note that backend systems may refer to these products by different names than their public-facing API names.
APIList value
Account InformationECA-CommercialAccountReporting
ACH OriginationACH-Originations
Wire TransferExternalRTPandWirePayments
RTP Send PaymentExternalRTPandWirePayments
Account ValidationVerificationServices
ACH InquiryACH Inquiry
Wire InquiryWires
RTP InquiryRTP-RTPInquiry
Previous DayInformation Reporting Previous Day
IntradayInformation Reporting IntraDay
Check Image RetrievalCheck Image Retrieval
Stop PaymentStop Payment
WebhooksDigital Disbursement Request
 

Some APIs have required request fields with KeyBank-provided values. All required request fields must be complete to be able to successfully submit a request.

Most of the required request values are environment specific, meaning that there are different values provided for different environments. The only exception is the ACH Origination API which can use the values provided for its required request fields in both environments.

APIParameterDescription
Account Validation APIadditionalIdSecondary client ID provided for each environment.
ACH Origination APIcollectionApplicationTypeSpecifies the client and account-specific application types for API payload and objects.
RTP Send Payment APIEPPIdA 32-character string that identifies you as the client. This is only required for POST requests to initiate or validate a payment.
Wire Transfer APIEPPId
Check Images APIpasswordUsername and password (NHID) shared via secure email. Use these credentials in the API payload, DefaultChecksRequest object.