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.

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:

Symptom Likely cause
Handshake fails immediately Certificate missing or not presented by client
Handshake fails, “unknown CA” Certificate not issued by / chained to a trusted CA
Handshake fails, cert rejected Certificate expired or revoked

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.