Getting Started Guide

clock 8-minute read calender Rel. 4.0.0 | updated Nov. 12, 2024

We've created this simple, user-friendly developer portal with you in mind. Here's a few good things to know first.

Key takeaways

  • You need to be an authenticated and authorized user with our developer portal to use our APIs. To get started, see our overview of the onboarding process.
  • After you onboard, you get your own private API keys and can access our test environment.
  • Get an access token to connect to your APIs and start building.

Want in?

Contact a Payments Advisor to learn more about the KeyBank API developer portal and we'll have someone contact you with more information! 
Contact us

01

Contact and consult

If you are interested in a particular API product or a group of APIs, sign up for our waitlist. KeyBank will follow-up with you to help get you started.

To work with KeyBank APIs, there needs to be an established agreement between the service provider (KeyBank) and the client (you). This agreement details the API services you want, its services, and settings. It also gathers important system information needed for the KeyBank onboarding team to configure and secure the provisioned app.

02

Determine API needs

Determine which APIs are needed, define the frequency of use, and the transaction activity timeframe. Some APIs require specific configurations and may have a certain object to include in the call. Also, be mindful of our rate limiting.

For each API, provide the following information:

  • General details like transaction volume
  • Call frequency (number of calls per second, number of calls per minute, etc.)
  • Call timeframe (e.g., 24 hours a day or only during business hours)

The KeyBank onboarding team will reach out via email communication for additional details, if necessary.

03

Set up security

It is essential to have a secure connection before we start exchanging data, especially data as sensitive as financial data. For us to trust one another and verify that our pathways are safe, private, and guarded, we need to know your IP address and exchange certificates.

A digital certificate verifies your identity and keeps your data safe. Think of it like a virtual ID card for a website, or in this case the developer portal. When you connect to the site, the certificate legitimizes your identity. Then, when making API requests and transferring data on a cloud network, the certificate helps encrypt the data.

We use a mTLS authentication mechanism. This means when you request a mTLS certificate, you will get a public certificate chain and a private key. On your end, configure your application with the private key and certificate. You do not need to share your private key with KeyBank. After we exchange certificates, you will use the private key to encrypt the exchange and KeyBank uses the public certificate chain to verify it.

Certificate requirements:

  • Must have a CSR and private key. Do not share the private key.
  • Must include the root, intermediate, and leaf.
  • File format can be *.pem, *.crt, or *.cer.
  • Certificates cannot be self-signed.
  • Issued by a trusted certificate authority organization like DigiCert.
  • Only one certificate is required for all APIs.

04

Grant access

KeyBank sets up your account entitlements. Entitlements authenticate your identity and contain the authorization rules for the APIs you have permission to access. Part of the account entitlements are the API keys.

You need API keys to create an access token required to make an API call. There are application credentials that authorize which API products you can access, and there are client credentials that authenticate you as a client partnering with KeyBank. We share this information with your privately and securely during our onboarding procedures.

KeyBank will set you up a test environment. You can use the test environment to get a better idea of how the API functions and how to integrate with your application. We share the environment details with you once setup is complete.

Common terms

Access token

A temporary token to that gives you permission to use the API. Use your API keys to generate the token. This is also known as a bearer token.

API consumer:

An authenticated developer portal user that has completed the onboarding process, has access to API services and possibly the KeyBank test environment.

API keys:

There are two sets of API keys that we privately share with you to authenticate and authorize your ability to use and access our API products. Can’t turn that engine without a key.

Authentication:

A method of identifying you and your application as a trusted and accepted source to exchange data. With authentication, we use your KeyBank client credentials (part of your API keys) to identify you.

Authorization:

A method of permitting access to certain APIs and services.

Certificates:

A digital exchange of several encrypted codes that verify your ability to connect with our API products safely, securely, and cautiously. These certificates typically expire annually.

CSR:

Certificate signing request is an encoded message that contains the information needed by the Certificate Authority (CA) to create your certificate. This can include your name, domain, organization information, or location.

Domain:

A human-readable name for an application or web address that identifies the name of the online application. Domain names are used to help set up web servers, communication, and other online services.

IP address:

The internet protocol address is a numerical label assigned to each device or application connected to the internet. Addresses can uniquely identify devices and route data to its intended destination.

mTLS:

Mutual Transport Layer Security is mechanism for the mutual authentication between the service provider and the client. No catfishing here. Digital certificates are exchanged and signed with the PKI framework.

Onboarding:

The process of helping KeyBank partners and API consumers get familiar with our suite of API products. This can include assessment, setup, and environment access.

PKI:

A public key infrastructure is a system to create, store, and distributes digital certificates. This framework matches the public keys to digital entities to authenticate the identity of users, devices, and services.

Pre-production:

A test environment that allows you try the API product using sample data.

Production:

KeyBank’s live environment that exchanges real proprietary data between your application and our API products.

Service agreement:

A contract between KeyBank and financial businesses and applications that intend to use and integrate with KeyBank’s suite of APIs. The service agreement identifies the API products allowed, data volume, and other specifics require to ensure a proper configuration of services.

We recommend that you always start your API builds with a health check. To perform a health check, you must have valid certificates exchanged with KeyBank and API keys to request an access token.

To ensure efficient and consistent API performance, we've placed a limit of 5 transactions per second (TPS) across all KeyBank APIs. API requests that exceed the rate limit receive an HTTP 429 response status code. If you've exceeded this limit, wait for at least 2 minutes before making another API call.

While we established the 5 TPS threshold to maximize stability and performance, we understand that your consumption needs might not fit within those limits. To request an increased rate limit, contact your KeyBank Client Success Manager.

The X-CorrelationId is a unique 36-digit alphanumeric identification code generated automatically for each API transaction. This field helps support teams at KeyBank quickly track down an inquiry or issue. The ID stays with the transaction so we can trace the chain of API operations in the event logs. If you see different X-CorrelationId values for the same transaction, this could indicate that duplicate requests.

KeyBank requires an OAuth 2.0 access token to authorize API calls. To make a call for a token, you must have access to our environments, your certificates, private key, and API keys. 

Copy and modify the cURL command template. Be sure to replace the curly brackets {{xxxx}} with your specific information.

  1. For line 1, identify the certificates.
    • For client.crt, enter the location of your certificate signing request (CSR). The file must be in one of these formats *.pem, *.crt, or *.cer.
    • For client.key, enter the name of your certificate’s private key file.
    • For ca.crt, enter the name of your certificate authority (CA) certificate.
  2. For line 2, identify the host. Enter the URL address for the KeyBank environment. Make sure to add scope=rs-read as a path parameter in the URL.
  3. For line 3, enter your application credentials (consumer_key and consumer_secret) API keys in Base64 encoded format. Use a trusted site to generate an encoded string for your consumer key and secret.
  4. For line 6, enter your client credentials from KeyBank. For client id enter your client_id API key and for client password, enter the client_secret API key from KeyBank.
cURL command template
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'
  • The response contains a field named access_token. Use this access token in the Authorization header when you call the API over a secure mTLS connection.
  • 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.

Request

Response

curl -X POST --cert client.crt --key client.key --cacert ca.crt \ 
  'https://partner-api.keybank.com/oauth/v1/token’
  -H 'Authorization: Basic KFddrcHQwQ3JDGQTamdqRUI0bEFHVVlHQcg'
  -H 'Content-type: application/x-www-form-urlencoded'
  -H 'Accept: application/json'
  -d 'Id=b1194a183b8e01&Key=165a15dfanqf1d60&grant_type=client_credentials'
curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \
  {
   "refresh_token_expires_in": "0",
   "api_product_list": "[API 1, API 2, API 3]",
   "api_product_list_json": [
      "API Inquiry",
      "API test product",
     ],
   "organization_name": "keybank-non-prod",
   "developer.email": "yourEmail",
   "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"
  }

What to expect

  1. You get a response with access token and information about which API products you can use, the refresh token time cycle, expiration time, etc.
  2. Select and copy the access_token value to use with your API requests.
  3. 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.

What's next?

  • If this all sounds nice to you, sign up to speak with a Payments Advisor. Our people will reach out to your people.
  • Read our API documentation to learn more about KeyBank’s API products. Or if you prefer to look under the hood, download an API specification file in YAML format.