When is a Certificate Required?   

Certificates are required when:

• The API uses HTTPS

• The server requires client authentication (mTLS)

• The server uses a self-signed certificate
  

Mutual Authentication (mTLS)  

In secure integrations, both client and server verify each other. This enhances security by ensuring that both the client and the server verify each other’s identities during the SSL/TLS exchange process.

       

• Server shares its certificate → Client validates

• Client shares its certificate → Server validates
  

The connection is established only if both are valid.

Before enabling mutual authentication, administrators must configure the necessary Key Store and Trust Store certificates.

Key Benefits

• Keeps data safe: It protects sensitive details shared between users and the service.
• Builds trust: Users feel more confident using a service when they know it’s secure.
• Supports compliance: Many security standards and regulations require certificates for data protection.
• Improves access: Some browsers block or warn users about sites that don’t have a valid certificate.
  

Key Concept

Key Store in Qntrl  

A Key Store securely stores the client’s private key and its associated certificate, which are used to authenticate the client to the server.
Qntrl supports two formats for Key Stores:

• Certificate and Private Key (uploaded separately)

• PFX / PKCS#12 files (bundled format)
  

A Trust Store holds certificates of servers that Qntrl trusts. When Qntrl makes an outbound HTTPS call (especially to servers with self-signed certificates), the server’s certificate must be trusted to establish a secure connection.

By adding the service provider’s certificate to Qntrl’s trust store, you ensure that all outbound requests verify the server’s authenticity.

Create a Certificate 

To create a new certificate in Qntrl, navigate to(settings)>> Advanced >> Certificate >> Click New Certificate.

1. Name: Enter a unique name for the certificate.
2. Certificate Type: Select the appropriate type based on how the client initiates requests. The corresponding file upload fields will appear based on your selection.
• Certificate & Key: Upload the certificate and private key as separate files.

• Certificate File
• Private Key File

• PFX/PKCS312: A single file containing both certificate and private key.

• PFX / PKCS#12 File

• Trust Store: Used when both client and server need to establish trust (commonly for self-signed certificates).
  
• Trust store File

• Java Keystore: Proprietary format for Java eco-system

• Mobile Provisioning: Provide the file for IOS application

3. Certificate Format  : Choose one of the following:
• PEM: Human-readable Base64 encoded format (commonly used).
• DER: Binary format used in certain systems.
4. Password  : If your certificate requires a password, enter it here. This is applicable for PFX/PKCS format.
5. Host: Enter the hostname (e.g., core.qntrl.com) for which the certificate applies.
6. Port: Default is 443. Modify if your API uses a different port.
   
7. Expiry Notification: You can configure alerts to be notified before the certificate expires:
• Enable Expiry Notification: Select this option to activate expiry alerts.
• Email Alert Configuration: Choose an existing email alert or create a new one by clicking New Email Alert.
• Expiry Warning Days: Define how many days prior to expiry the notification should be triggered.
• Notification Frequency: Select how often notifications should be sent (e.g., daily or weekly).
8. Click Save to create the certificate. 
   

• Subject

• Issuer

• Valid From

• Expires On

Certificate Usage During Execution   

When an API request is executed:

• Qntrl retrieves the certificate based on the configured host and port.

• If multiple certificates match, the latest valid (non-expired) certificate is selected automatically. 

In secure production environments, certificates are typically issued by trusted Certificate Authorities (CAs). In testing or sandbox setups like Bridge, dummy or self-signed certificates are often used instead.

Using Certificates in Outbound REST APIs   

1. Navigate to(settings)>> WEB SERVICES >> Outbound >> Click REST.
   

2. Navigate to the Settings tab.
3. Enable the Enable SSL Certificate Verification toggle.
4. The system retrieves the client certificate and trust store certificate, then validates the certificate against the host configured in the certificate section.
5. If the client certificate or host does not match, the API call will fail with an SSL Certificate Not Found error.
   

Incorrect passwords, hostnames, or expired certificates will result in failed requests.

Edit/ Delete a Certificate   

1. Navigate to(settings) >> Advanced >> Certificate.
2. Click the action menu (...) next to the certificate name.
3. Choose Edit or Delete:

• Edit: Select this option to make changes to the certificate details. After editing, click Save to apply the changes.
• Delete: Use this option to permanently remove unused or invalid certificates from your account.

Deleting a certificate is irreversible. Make sure it’s no longer in use before proceeding.

Troubleshooting  

1. SSL Certificate Not Found  

• Ensure the host name in the certificate matches the one in the API configuration.

• Verify that SSL Certificate Verification is enabled under Settings.

2. Invalid Certificate Format  

• Check if the correct format (PEM/DER) is selected while uploading.

3. Password Errors  

• If your certificate is password-protected, ensure the correct password is entered.

4. Expired Certificates  

• Validate the expiry date of the certificate in the properties section and renew if necessary.

5. PLS Errors  

• Occur when the server certificate isn’t trusted by Java’s default trust store. Use Trust Store to load custom server certificates manually.