Enhanced API Security with Mutual TLS (mTLS) Authentication

1. 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. Important: mTLS is opt-in to configure, but once configured for a tenant, it becomes mandatory (enforced) for that tenant’s requests — not optional on a per-request basis. Tenants that have not configured mTLS are unaffected and continue using token-based authentication only.

2. 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

3. 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.

4. 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.

5. mTLS Enforcement

Once mTLS is configured and activated for a tenant, it is enforced for all subsequent requests from that tenant — requests that do not present a valid, registered client certificate will be rejected at the TLS layer, before reaching the application.

⚠️ Enforcement applies only to tenants who have configured mTLS. If mTLS is not configured in a tenant’s subscription, authentication continues unchanged (token-based only).

If you plan to configure mTLS, ensure your integration is fully tested with a valid client certificate before enabling it for your tenant, as there is no partial or soft-enforcement mode — once enabled, it applies immediately to all requests.

6. Certificate registration model: Bindings and Identities

Each client can register one or more certificates. Registering a certificate is a two-step process: a Binding is created in our configuration first, then one or more Identities under it.

6.1 Binding — associates a certificate with your client

A Binding is the link between your client and one specific certificate, and it’s also where that certificate’s revocation-checking behavior is configured.

• One Binding per certificate. If you use more than one certificate — for different integrations under the same client, or because you’re rotating certificates — each certificate gets its own Binding.
• Several Bindings per client are allowed. A single client isn’t limited to one certificate; it can have multiple active Bindings at once, each pointing at a different certificate.

Each Binding defines how revocation is checked for its certificate:

Which revocationMode values are actually usable for a given certificate depends on who issued that certificate to the client — not every CA offers an OCSP responder, so crl or none may be the only options depending on the issuer.

revocationFailMode only applies when revocationMode is ocsp, and controls what happens if the OCSP responder can’t be reached:

6.2 Identity — the fields checked on the certificate

Once a Binding exists, we can register one or more Identities under it. An Identity is one field on the presented certificate that must match an expected value for the certificate to be accepted as belonging to that Binding’s client. A single certificate can be identified by more than one field at once — each one is its own Identity record. These values have to be provided by the client.

7. 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.

8. 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).

9. 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.

10. 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.

11. FAQ

Do I have to use mTLS? No, it’s optional to configure. However, once you configure mTLS for your tenant, it becomes mandatory — all requests must present a valid client certificate. If you never configure mTLS, 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.

12. 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.