Certificates

For KeyBank APIs, all integrations require mutual TLS (mTLS) authentication to protect the exchange of private and sensitive financial data. With mTLS, both the client and the server prove their identity using digital certificates. It is a two-way authentication mechanism that uses certificates with digital signatures tied to public keys within a Public Key Infrastructure (PKI) framework. 

PKI is a combination of technology, policies, and processes that allow you to securely exchange information over the internet.

Key PKI Components

• Certificates: Digital “ID cards” that prove the identity of a website, server, or user by binding a public key to an identity (like a domain name). Certificates are issued and signed by a Certificate Authority (CA).
• Certificate Authorities (CAs): Trusted organizations that issue, validate, and revoke digital certificates.
• Public and private keys: A pair of cryptographic keys—one public, one private—that work together to encrypt and decrypt data.
  • The private key is secret and must be protected.
  • The public key is shareable and embedded in the certificate.
• Trust model: A set of rules and process that determine which certificates are considered valid and trusted by browsers, apps, and systems.

In summary, PKI makes sure that when you connect to an API, you know who you’re talking to and that the data is encrypted. 

Certificate chain

PKI relies on a chain of trust, a hierarchical set of certificates that validate one another. 

1. Root CA: The trust anchor. This top-level certificate is widely trusted and used to sign intermediate certificates.
2. Intermediate CA: Links the root to leaf (end-entity) certificate. There may be one or more intermediates in the chain. Server and clients send these in the TLS handshake so the receiver can build and validate the chain.
3. Leaf (end-entity) certificate: Your unique mTLS client certificate that identifies your domain or application. It is signed by an intermediate CA. 

To connect to KeyBank APIs, you must provide:

• A complete certificate chain (root, intermediate, and leaf) in one file (e.g., client_chain.pem, client_chain.crt, or client_chain.cer).
• Certificates must be issued by a trusted CA.
• Certificates must support client and server authentication.
• Self-signed certificates are not accepted.

There are multiple way to generate and configure certificates depending on your system and CA. The following guidelines outline the common requirements and steps.

Public/private key pair

The public and private keys work together to encrypt and decrypt information exchanged between systems. 

• Generate a private key using a key manager or command-line tool. Keep your private key secure and never share it with anyone, including KeyBank.
• Derive a public key from the private key. The public keep is embedded in your certificate and can be shared. 

Certificate Signing Request

Create a Certificate Signing Request (CSR) to share details about your identity, application, and public key with a trusted CA.

Common attributes include:

• Common Name (CN): The fully qualified domain name (FQDN) for the certificate (e.g., www.example.com).
• Organization (O): Your company or organization’s legal name.
• Organizational Unit (OU): Department or division within the organization (e.g., IT, Security).
• Locality (L): City where your organization is located.
• State/Province (ST): Full name of the state or province.
• Country (C): Two-letter ISO country code (e.g., US, CA).
• Email address: Contact email for certificate-related communication.
• Key size and algorithm: Common choices: RSA 2048-bit or 4096-bit, or ECC curves.

Certificate issuance 

Chose a reliable CA and submit your CSR. The CA will verify the accuracy of the CSR. If all requirements are met, the CA issues the certificates - root, intermediate, and leaf.  KeyBank recommends the following CAs:

• Comodo
• DigiCert
• Entrust
• GeoTrust
• GlobalSign
• GoDaddy
• SecureTrust
• USERTrust (Sectigo)
• Verisign

Configure certification

Assemble your certificate chain and configure your system for KeyBank API calls:

• Use client_chain.pem as your public client certificate bundle.
• Use client.key as your private key.
• Use the KeyBank CA bundle to validate KeyBank’s server certificates.

Verify connection

Test your setup by performing an API health check to ensure the certificate chain is correct and the mTLS connection is successful.