Access controls

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-issued authentication parameters.

It is important to have a basic understanding of the difference between authorization and authentication. Simply put, authentication verifies your identity and authorization determines which APIs you can access.

Authentication: Use your credentials like API keys, to identify the user account making the call.
Authorization: Use your access token in your API requests for APIS you are permitted to access.

Members only

KeyBank requires an OAuth 2.0 access token to authorize API calls. To make a call for a token, you must be completely onboarded as a KeyBank partner.

Interested? Learn how to get started.

API keys

API keys are a string of alpha-numeric characters that make up unique, client-specific identifiers. You must have valid API keys to request an access token.

KeyBank provides API keys for both application and client credentials, which are required for both Non-Production (like the simulator) and Production environments.

Application credentials verify that you have permission to access KeyBank APIs.

consumer_key
consumer_secret

Client credentials identifies you as a KeyBank client. Always use the client ID together with the client secret to keep your application secure.

client_id
client_secret

How to get an access token

To call KeyBank APIs, you must first request an OAuth 2.0 access token. In your token request, provide your certificates, environment details, and credentials. The API gateway validates your request, and the authentication server issues the token if all requirements are met. This token must be included in the header of API calls.

Request

Use the cURL command template to request an access token. Replace the curly brackets ({{ }}) with your specific information.

Path fields

PATH FIELD	TYPE	DESCRIPTION
client.crtrequired	string	Location and name of your certificate signing request (CSR). Valid file formats: .pem, .crt, or *.cer.
client.keyrequired	string	Location and name of your certificate’s private key file.
ca.crtrequired	string	Location and name of your certificate authority (CA) certificate.
hostrequired	string	The host URL address for the KeyBank environment. Add `scope=rs-read` as a path parameter in the URL. This is required for read-only access to your token.

Header fields

HEADER FIELD	TYPE	DESCRIPTION
Authorizationrequired	string	Your application credentials (`consumer_key` and `consumer_secret`) API keys in Base64 encoded format.
Content-Typerequired	string	The format of how the information is returned. For a bearer token, use application/x-www-form-url-encoded.
Acceptrequired	string	Identify acceptable media types for the response. Use application/json.

Body (form data)

BODY FIELD	TYPE	DESCRIPTION
Idrequired	string	Your KeyBank client ID (client_id).
Keyrequired	string	Your KeyBank client secret (client_secret).
grant_typerequired	string	Use client_credentials to specify that the token is granted by client ID and secret.

cURL command template

curl -X POST \
  --cert {{path/to/client.crt}} \
  --key {{path/to/client.key}} \ 
  --cacert {{path/to/ca.crt}} \
  ‘{{host}}/oauth/v1/token?scope=rs-read' \
  -H 'Authorization: Basic {{Base64_consumerKey_colon_consumersecret}}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'Id={{client_id}}&Key={{client_secret}}&grant_type=client_credentials'

Response

NAME	TYPE	DESCRIPTION
refresh_token_expires_in	integer	Time in seconds that the token will expire. Default time is 86399 seconds (one second short of 24 hours).
api_product_list	array	List of API products that you are permission to access with the issued token.
api_product_list_json	array	List of API products in Json format that you are allows to access with your token.
organization_name	string	The organization name associated with the host.
developer.email	string	Email address associated with the client.
token_type	string	Type of token being request. The access token is referred to as the 'bearer token'.
issued_at	string	System-coded timing for when the token was granted to the client.
client_id	string	The client ID used in the request is returned to establish that this token is associated with this identity.
access_token	string	The encoded access token to use in the Authorization header for API calls.
application_name	string	The system assigned ID for the application name associated with the client account.
scope	string	The read and write permissions authorized for the account and product.
Id	string	The name or ID associated with the client account.
expires_in	integer	Token expiration time in seconds. The default is 86399, one second before 24 hours.
refresh_count	integer	The amount of times you can refresh the access token. This is typically zero, '0'.
status	string	The status of the request. For successful token requests, the status is approved. Valid values: approved, rejected.

In the response, look for these key parameters:

access_token — Use this access token in the Authorization header when you call the API over a secure mTLS connection. The access token remains valid for 24 hours. If it expires, try the refresh token to receive a new access token and pass in the API request.

api_product_list — Provides a list of the API products you can are authorized to use. If you are unable to retrieve an access code, reassess your setup, review your API keys, and make sure you are properly connected to the environment before you try again.

API product list values

API	List value
Account Information	`ECA-CommercialAccountReporting`
ACH Origination	`ACH-Originations`
Wire Transfer	`ExternalRTPandWirePayments`
RTP Send Payment	`ExternalRTPandWirePayments`
Account Validation	`VerificationServices`
ACH Inquiry	`ACH Inquiry`
Wire Inquiry	`Wires`
RTP Inquiry	`RTP-RTPInquiry`
Previous Day	`Information Reporting Previous Day`
Intraday	`Information Reporting IntraDay`
Check Image Retrieval	`Check Image Retrieval`
Stop Payment	`Stop Payment`
Webhooks	`Digital Disbursement Request`

200 Response

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[ExternalRTPandWirePayments, Wires]",
    "api_product_list_json": [
        "Wires",
        "ExternalRTPandWirePayments"
    ],
    "organization_name": "keybank-non-prod",
    "developer.email": "frankDev@devteam.apigateway.io",
    "token_type": "BearerToken",
    "issued_at": "2255448892",
    "client_id": "KBConsumerKey",
    "access_token": "gPd4ZXMi927aoWhvmc",
    "application_name": "9IIa42-134320dk32s",
    "scope": "apiauth-read apiauth-write rs-create rs-delete rs-oauth rs-read rs-update rs-write",
    "Id": "KBClientId",
    "expires_in": "86399",
    "refresh_count": "0",
    "status": "approved"
}

Troubleshooting

If you submit a request and no token is returned, use these troubleshooting steps for common 4xx errors.

401 Unauthorized

Check the Authorization header. Make sure it is Basic {base64(consumer_key:consumer_secret)}. If you rotated credentials, you need to regenerate the Basic header .
Confirm the Base64 input format is exactly consumer_key:consumer_secret.

400 Bad Request

Verify form body keys, Id and Key.
- Make sure that token grant type is set to client credentials: grant_type=client_credentials.
- Ensure scope=rs-read is present in the query string.

403 Forbidden

Your IP may not be allow‑listed for this environment. Confirm you’re using the exact host provided during onboarding.

404 Not Found

You could be passing an expired certification or the incorrect certificate details, causing a mTLS handshake failure.
Check your certificate and verify its health.
- Confirm your certificate chain (root, intermediate, and leaf).
- Check that the certificate file format is valid (.pem, .crt, .cer).
- Make sure the client.crt name and path match the client.key.
- Confirm ca.crt trusts the KeyBank server certificate.

If you are receiving errors related to your certificates, review and verify that all certificate requirements have been satisfied as defined in Certificates.