REST API traffic encryption

Infobip accepts public REST API traffic over TLS 1.2 and TLS 1.3 only. Learn which cipher suites are supported and how Infobip manages security changes to avoid interruptions to your integration.

TLS encryption of HTTP traffic

Infobip uses Transport Layer Security (TLS) to securely transfer data over the network. Only the most secure TLS versions and cryptographic algorithms are supported. TLS versions 1.0 and 1.1 are not supported.

Infobip supports the following TLS versions and cipher suites.

TLSv1.3 (server-preferred order):

• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_GCM_SHA256
• TLS_AES_128_CCM_SHA256

TLSv1.2 (server-preferred order):

• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_DHE_RSA_WITH_AES_128_CCM
• TLS_DHE_RSA_WITH_AES_256_CCM
• TLS_DHE_RSA_WITH_AES_128_CCM_8
• TLS_DHE_RSA_WITH_AES_256_CCM_8
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

TLS/SSL change policy

Infobip notifies customers of TLS/SSL changes as follows:

• TLS version changes: You are notified at least 6 months in advance.
• TLS cipher suite changes: You are notified at least 60 days in advance.
• SSL certificate changes: You are notified at least 60 days before the change. The notification includes trust chain information and the new certificate on a testing endpoint.

All changes are posted on the Infobip Status(opens in new tab) page with three states: Scheduled, In progress, and Completed.

TLS/SSL certificate changes

Infobip uses SSL certificates signed by DigiCert. The issuing intermediate CA is RapidSSL TLS RSA CA G1, a DigiCert CA. Public REST API endpoints have a certificate valid for 1 year, renewed accordingly. If you do not pin the certificate and have automated trust store updates enabled, you are not affected.

Who is affected [#who-is-affected-tlsssl-certificate-changes]

Leaf certificate pinning: This practice has high agility costs and limitations. Use mTLS (client certificate authentication) as a more secure alternative. Contact Support for information. If you choose leaf certificate pinning, proactively monitor and update pinned certificates in a timely manner.

Manually operated trust store: Most trust stores update automatically, but if you operate yours manually, Infobip relies on the DigiCert PKI. Download all CAs from the DigiCert Root CA(opens in new tab) website. If you are not bound to trust only one CA, install CAs that Mozilla trusts in PEM format instead. Before trust chain changes, information about the new CA Common Name (CN) is added at least 60 days in advance. You can then import the CAs alongside the ones you already have.

TLS test endpoints [#tls-test-endpoints-tlsssl-certificate-changes]

When a certificate change is scheduled, Infobip makes the certificate available on test endpoints. Test from production environments using the same trust store.

Generic endpoint pattern: <location> is the data-center code from your Base URL (for example, us for a US location).

Non-wildcard certificates (for example, api.infobip.com): Use the --resolve flag with the test endpoint IP from the change notification (172.201.176.225 in this example):

Wildcard certificates: Use the location-specific test URL directly:

The following is an example of a successful response from tls-test.api.infobip.com. Values are an example:

The following table describes the response fields:

Prepare for a certificate change [#prepare-for-a-certificate-change-tlsssl-certificate-changes]

If you manually operate trust stores or pin certificates, follow these steps when a change is announced:

1. Subscribe to alerts: Subscribe to the Status(opens in new tab) page to receive change notifications.
2. Test: Use the provided test endpoints to test TLS connections with any HTTP client.
3. Update configuration: If the TLS connection fails, update the local SSL configuration.
4. Verify: After each local configuration change, verify the test TLS endpoint connection works.

Troubleshoot TLS errors

Detect possible issues by checking test endpoints before the scheduled certificate replacement.

TLS chain errors [#tls-chain-errors-troubleshoot-tls-errors]

A TLS chain error indicates the local system or client does not have the Infobip CA configured as expected. The following is an example error:

To resolve a TLS chain error:

1. Check which CA certificates are present on the client system. Download and install CAs that Mozilla trusts(opens in new tab) in PEM format.
2. Verify that the client loads the CA certificate from the correct directory.

SSL handshake errors [#ssl-handshake-errors-troubleshoot-tls-errors]

SSL handshake errors happen when the client does not support the TLS version or cipher suites Infobip requires. The following is an example protocol error:

The following is an example handshake failure due to unsupported ciphers:

To resolve an SSL handshake error:

• If the client is behind a firewall, SSL inspection, or VPN, check whether those devices support the TLS versions and ciphers that Infobip supports.
• Check whether the client supports the available TLS versions and ciphers.
• Explicitly configure the client to use the highest supported TLS version if possible.