Enhanced API Security with Mutual TLS (mTLS) Authentication

Overview

In addition to token-based (OAuth) authentication, you can now secure your API integration with mutual TLS (mTLS). With mTLS enabled, both your client and our server present and validate certificates during the TLS handshake, before any request reaches the application layer.

mTLS is opt-in per tenant and does not replace token authentication — it adds a transport-level check on top of it. Existing integrations that don’t enable mTLS are unaffected.

Authentication flow with mTLS enabled

1. Your client presents its certificate during the TLS handshake.
2. Our gateway validates the certificate: chain of trust against our trusted CA(s), expiry, and revocation status (CRL/OCSP).
3. If the certificate is valid, the request proceeds to standard OAuth bearer-token validation, unchanged.
4. Both checks must pass for the request to succeed.

Client cert (TLS handshake) → cert validated → bearer token (application layer) → request processed

Prerequisites

• A client certificate issued by a CA we trust, or your CA’s chain of trust shared with us in advance.
• Your existing OAuth token setup — mTLS does not replace it.

Onboarding

1. Contact your integration/account team to enable mTLS for your tenant.
2. Provide your client certificate (or CA chain) to register against your tenant configuration.
3. Once activated, your requests must present the registered certificate — requests without it will be rejected.

mTLS is enabled per tenant, not globally. Enabling it does not affect other tenants or other Youforce APIs you may consume without mTLS.

Certificate requirements

• Valid, non-expired certificate at request time.
• Chain of trust to a CA we recognize.
• Additional binding constraints (e.g. Subject/CN matching your registered domain) may apply — confirm current requirements with your integration contact, as these can evolve.

mTLS Endpoint (Coexistence Notice)

Youforce now also exposes an mTLS-secured endpoint at:

• mtls.api.youforce.com
• mtls.data.youforce.com

It does not replace the existing host — both coexist, and which one to use depends on the client’s configuration and integration requirements.

⚠️ Ensure client/integration configs are pointed at the correct host for their use case, and that the corresponding certificate is correctly referenced/trusted where required (especially for clients enforcing mutual TLS).

Error handling

If your certificate is missing, expired, untrusted, or revoked, the TLS handshake will fail before any application-level response is generated — you will see a TLS-level connection error, not an API error payload. Check:

Application-level errors (e.g. invalid bearer token) still return normal API error responses — that layer is unchanged.

Certificate rotation & expiry

• Certificates expire and must be rotated before their expiry date, or requests will start failing at the TLS layer.
• Plan rotation ahead of expiry; coordinate the new certificate registration with your integration contact so there’s no gap in validity.
• If your certificate is compromised, notify us immediately so it can be revoked — further requests using it will be rejected right away.

FAQ

Do I have to use mTLS? No. It’s optional per tenant. If you don’t enable it, nothing changes for your integration.

Does mTLS replace my OAuth token? No. Both are required together once mTLS is enabled for your tenant — certificate at the transport layer, token at the application layer.

Will this affect other APIs I consume from Youforce? No. mTLS is scoped to your tenant configuration and does not apply to other tenants or unrelated integrations.

List of trusted CAs

Our organization maintains a defined list of trusted Certificate Authorities (CAs) for validating TLS/SSL certificates across our infrastructure. The following CAs are recognized and trusted: DigiCert, GlobalSign, Sectigo, Entrust, QuoVadis, and PKIoverheid (Dutch government PKI hierarchy). Any certificate issued by a CA not included in this list should not be trusted without prior review and explicit approval, in line with our security and compliance policies. This list should be periodically reviewed to ensure continued alignment with industry standards and regulatory requirements (including GDPR/AVG where applicable), and any additions or removals must follow the established change management process.

Note: certificates for DigiCert, GlobalSign, Sectigo, and Entrust are downloaded directly from the listed URL via script/automation. For QuoVadis and PKIoverheid, however, the certificate is downloaded manually from their website, since they don’t provide a stable direct link to the certificate file.