Note: This article supersedes the earlier draft 2022-11-30-API-Certificates.md which covered older API Connect versions. This version reflects the v12 certificate management model.

API Connect uses certificates extensively — for TLS termination on the gateway, for MTLS between components, for the portal, and for analytics ingestion. Managing these certificates — knowing when they expire, rotating them before they cause an outage, ordering new ones from your CA — is a critical operational task that many teams handle poorly until an incident forces them to.

This article is a practical guide to certificate management in API Connect v12. I’ll cover the certificate types, how to import and rotate certificates, integration with external Certificate Authorities, and CLI/API approaches.

Table of Contents

  1. Certificate Types in API Connect v12
  2. Certificate Management UI
  3. Importing Certificates
  4. Certificate Rotation
  5. Ordering Certificates from an External CA
  6. CLI/API Approaches
  7. Monitoring Certificate Expiry
  8. Common Certificate Errors

Certificate Types in API Connect v12

API Connect v12 has several distinct certificate use cases:

Gateway TLS Certificates

Used by the gateway to terminate TLS connections from API consumers. These are the certificates your API consumers see when they call your APIs.

  • Type: TLS Server Certificate
  • Where: Gateway service configuration
  • Rotation: When replacing or renewing

Client MTLS Certificates

Used for mTLS (mutual TLS) authentication between API Connect components. These certificates prove the identity of one API Connect component to another.

  • Type: MTLS Client Certificate
  • Where: Truststores, client profiles
  • Rotation: When the certificate expires or is compromised

Portal TLS Certificates

Used for the Developer Portal (CMS Portal) HTTPS endpoint.

  • Type: TLS Server Certificate
  • Where: Portal service configuration
  • Rotation: Same as gateway TLS

Analytics Certificates

Used for MTLS between Analytics and the ingestion endpoint.

  • Type: MTLS Client + Server
  • Where: Analytics service configuration
  • Rotation: Typically on upgrade or when expiring

Signer (CA) Certificates

Certificate Authority certificates used to sign other certificates. API Connect maintains a trust chain using these.

  • Type: CA/Signer Certificate
  • Where: Truststores
  • Rotation: When your CA rotates its signing certificate

Certificate Management UI

API Manager Certificate Management

  1. Log into API Manager
  2. Navigate to Resources → Certificates (or Manage → Certificates depending on your UI version)
  3. You’ll see a list of all certificates managed by API Connect

[Screenshot Placeholder: /images/apic-certificates-list.png] The API Connect certificate management screen showing managed certificates, expiry dates, and type.

Certificate Status Indicators

Certificates are colour-coded by status:

  • Green: Valid, >30 days until expiry
  • Yellow: Expiring soon, <30 days
  • Red: Expired or critical (<7 days)
  • Grey: Unknown or not yet validated

Importing Certificates

Importing a Server Certificate via UI

  1. Navigate to Resources → Certificates
  2. Click Add → Server Certificate
  3. Fill in:
    • Certificate name: A descriptive name (e.g., api-gateway-tls-2026)
    • Certificate file: The PEM or DER encoded certificate file
    • Private key file: The corresponding private key (PEM format)
    • Passphrase: If the private key is encrypted
  4. Click Import

Importing a CA/Signer Certificate via UI

  1. Navigate to Resources → Certificates
  2. Click Add → CA Certificate (or Signer Certificate)
  3. Fill in:
    • Certificate name: A descriptive name
    • Certificate file: The CA certificate PEM file
  4. Click Import

Importing via CLI

# Import a TLS certificate to the gateway service
apic certificates:import \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --catalog ${CATALOG} \
  --type server \
  --name "api-gateway-tls-2026" \
  --cert-file ./server.crt \
  --key-file ./server.key \
  --key-password-file ./key-password.txt

Certificate Rotation

Certificate rotation is the process of replacing an existing certificate with a new one. In API Connect v12, rotation should be done before expiry to avoid service disruption.

Rotation Process

  1. Order or generate the new certificate (see next section)
  2. Import the new certificate into API Connect (don’t delete the old one yet)
  3. Associate the new certificate with the relevant service (gateway, portal, analytics)
  4. Test connectivity to ensure the new certificate is being used
  5. Remove the old certificate after confirming the new one is active

Important: When rotating a certificate used for TLS termination, coordinate with your consumers if they’re doing certificate pinning. Provide the new certificate in advance.

Certificate Reordering

If you have multiple certificates for a single endpoint (e.g., during a migration), you can reorder them:

# List current certificate order
apic certificates:list \
  --server ${MANAGEMENT_SERVER} \
  --service ${GATEWAY_SERVICE_ID} \
  --fields name,id,order

# Set a certificate as the primary (first in chain)
apic certificates:set-primary \
  --server ${MANAGEMENT_SERVER} \
  --service ${GATEWAY_SERVICE_ID} \
  --certificate ${CERTIFICATE_ID}

Ordering Certificates from an External CA

Via DigiCert, Let’s Encrypt, or Your Internal CA

The process varies by CA, but the general workflow is:

  1. Generate a CSR (Certificate Signing Request)
# Generate a private key
openssl genrsa -out server.key 2048

# Generate a CSR
openssl req -new -key server.key -out server.csr \
  -subj "/C=GB/ST=London/L=London/O=MyOrg/CN=api.example.com"
  1. Submit the CSR to your CA — they provide the signed certificate
  2. Import the certificate into API Connect (as described above)

Automatic Certificate Management

If you’re running on OpenShift with cert-manager, you can automate certificate lifecycle:

# cert-manager ClusterIssuer example for API Connect
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: ops@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
    - http01:
        ingress:
          class: openshift-default
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: api-gateway-tls
spec:
  secretName: api-gateway-tls-secret
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - api.example.com
  duration: 8760h  # 1 year
  renewBefore: 720h  # 30 days

cert-manager will automatically request and renew the certificate, storing it in a Kubernetes Secret that API Connect can reference.

CLI/API Approaches

Listing All Certificates

apic certificates:list \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG}

Getting Certificate Details

apic certificates:get \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --certificate ${CERT_ID}

Returns: subject, issuer, serial number, validity dates, fingerprint (SHA-1 and SHA-256).

Deleting a Certificate

apic certificates:delete \
  --server ${MANAGEMENT_SERVER} \
  --org ${PROVIDER_ORG} \
  --certificate ${CERT_ID}

Warning: Deleting a certificate that’s in active use will cause TLS failures. Ensure the certificate is no longer referenced before deletion.

Via REST API

# List certificates
curl -X GET \
  "https://${MANAGEMENT_SERVER}/api/orgs/${ORG_ID}/certificates" \
  -H "authorization: Bearer ${TOKEN}" \
  -H "accept: application/json"

# Import a certificate
curl -X POST \
  "https://${MANAGEMENT_SERVER}/api/orgs/${ORG_ID}/certificates" \
  -H "authorization: Bearer ${TOKEN}" \
  -H "content-type: multipart/form-data" \
  -F "cert=@server.crt" \
  -F "key=@server.key" \
  -F "name=api-gateway-tls-2026"

Monitoring Certificate Expiry

Build Your Own Monitoring

#!/usr/bin/env bash
# check-cert-expiry.sh — monitor certificate expiry
# Run via cron: 0 8 * * * /opt/scripts/check-cert-expiry.sh

MANAGEMENT_SERVER="mgmt-api.example.com"
TOKEN_FILE="/opt/secrets/apic-token.txt"
TOKEN=$(cat $TOKEN_FILE)
EXPIRY_WARNING_DAYS=30

# Get all certificates
certs=$(curl -s -X GET \
  "https://$MANAGEMENT_SERVER/api/orgs/${ORG_ID}/certificates" \
  -H "authorization: Bearer $TOKEN" \
  -H "accept: application/json")

echo "$certs" | jq -r '.[] | "\(.name): expires=\(.validity.end)"' | while IFS=: read -r name expiry; do
  expiry_epoch=$(date -d "$expiry" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$expiry" +%s 2>/dev/null)
  now_epoch=$(date +%s)
  days_until=$(( (expiry_epoch - now_epoch) / 86400 ))
  
  if [ "$days_until" -lt "$EXPIRY_WARNING_DAYS" ]; then
    echo "ALERT: $name expires in $days_until days ($expiry)"
  fi
done

Using the API Connect Alerts System

Configure alerts for certificate expiry via the API Manager:

  1. Navigate to Manage → Alerts → Certificate Expiry
  2. Set threshold (e.g., 30 days, 14 days, 7 days)
  3. Set notification (email, webhook)

Common Certificate Errors

Error: SSLHandshakeException: No subject alternative names present

Cause: The certificate’s SAN (Subject Alternative Name) doesn’t include the hostname being used to connect. Fix: Re-issue the certificate with the correct SAN entries.

Error: PKIX path validation failed: algorithm constraints check failed

Cause: The certificate uses a signature algorithm that the JVM or DataPower considers weak (e.g., SHA-1, MD5). Fix: Re-issue the certificate using SHA-256 or stronger.

Error: Certificate is not yet valid

Cause: System clock skew — the current time is before the certificate’s notBefore date. Fix: Sync the system clock on the client/gateway.

Error: Certificate chain incomplete

Cause: The server certificate was imported but the intermediate CA certificate was not. Fix: Import the full certificate chain (server cert + intermediate(s) + root).

Summary

Certificate management in API Connect v12 is straightforward once you understand the certificate types and the import/rotation workflow. The key operational practices are:

  1. Monitor proactively — don’t wait for expiry alerts to fire before acting
  2. Rotate before expiry — give yourself at least 30 days of overlap
  3. Automate where possible — consider cert-manager for Kubernetes deployments
  4. Test rotation — practice certificate rotation in non-production before you need to do it under pressure

A certificate outage is avoidable. With the tools in this article, you can build a robust certificate management process for your API Connect v12 deployment.

Questions about API Connect certificates? Find me on Twitter @cminion.