FAQs

Most of the answers you can find in our content, but some information is worth calling out. Here in Frequently Asked Questions (FAQs), KeyBank answers common inquiries and provides useful insights to equip you with the right knowledge.

What is a certificate?

Certificates are electronic documents that verify your identity. Your certificate cannot be self-signed. It must be issued and signed by a publicly trusted certificate authority.

Think of a digital certificate like a virtual ID card for a website, or in this case the developer portal. When the client connects to the site, the certificate legitimizes the client’s identity. When the client wants to transfer data on a cloud network, the certificate helps encrypt the data.

What kind of certificate do I need?

Connection to the KeyBank network requires a mutual TLS two-way authentication mechanism that uses digital certificates signed using the public key infrastructure (PKI) framework. Therefore, KeyBank requires a public certificate chain from the client that meets the following requirements:

• Only one certificate is required for all APIs.
• The certificate must have a CSR and private key.
• The certificate chain must include the root, intermediate, and leaf.
• The certificate can be in any format, like *.pem, *.crt, or *.cer.
• Certificates cannot be self-signed.
• The certificate must be issued by a trusted certificate authority organization like DigiCert.

What is a certificate authority (CA)?

A digital notary for certificates issued by a trusted third party. KeyBank recommends DigiCert, Verisign, Comodo, Entrust, GeoTrust, GlobalSign, GoDaddy, SecureTrust, or USERTrust (Sectigo).

Are access and bearer tokens the same thing?

Pretty much! Bearer token is a more formal term for access token. Essentially, tokens are the primary way to access an API secured with OAuth 2.0. Only authenticated users with client credentials can request a token.

What is OAuth?

OAuth 2.0 is the industry-standard protocol for secure authorization and controlled API access. Once successfully authenticated with the API keys above, the authorization server issues an access token directly to the client. We use bearer tokens as our access tokens. This bearer token can then be used to make authorized requests to our APIs. Bearer tokens must be refreshed every 24 hours.

How do I verify my connection?

Use your KeyBank credentials to get an access token. Run the following cURL command. The certificate files must be identified in the first line. Application credentials are Base64 encoded and used with your client credentials to get an access token.

curl -X POST --cert {{client.crt}} --key {{client.key}} --cacert {{ca.crt}} \ 'https://{{HOST}}/oauth/v1/token' \
-H 'Authorization: Basic {{base64(CONSUMER_KEY:CONSUMER_SECRET)}}' \
-H 'Content-Type: application/x-www-formurlencoded' \
-H 'X-CorrelationId: {{transaction identifier at overall system level}}' \
-d 'Id={{CLIENT_ID}}&Key={{CLIENT_SECRET}}&grant_type=client_credentials'

How do I know what API products I have access to?

When you request an access token, the response includes an attribute apiProductList. Review this field to see what APIs you have access to. If you need to request another API product, contact your Payments Advisor.

What is a X-CorrelationId?

The X-CorrelationID parameter is a unique identifier created for each API operation. This ID returns in error responses to help you trace this transaction the chain of API operations in event logs. The system automatically generates a random alphanumeric ID in the response.

What is a UUID?

UUID stands for Universally Unique Identifier. This is a useful attribute to recall a transaction before the next batch cycle runs. You create this value. The can be an alphanumeric value with a maximum length of 45 characters. For example, a random UUID value can be 5ea39056-49gb-4714-b941-e52b1bec7. The batch and the individual UUID can be the same. KeyBank recommends that you use different UUID values.

Note, since the UUID field is required to undo an ACH payment request, KeyBank strongly encourages the UUID is included with all ACH Origination calls.