mTLS

Available on requestContact your Bird representative to enable it for your organization.

Mutual TLS (mTLS) adds a certificate check to the TLS handshake in both directions. Each direction has its own settings. You can set up one direction or both.

Each party keeps its own private keys. For API requests, you give us the public certificate of your certificate authority (CA). For webhook deliveries, we give you a certificate signing request (CSR), and you return the signed public certificate.

Before you start

• Contact your Bird representative to enable API mTLS, webhook mTLS or both for your organization. Each direction is enabled separately.
• Get a role with write access to the access_restrictions scope in the workspace. To send webhook test events, also get write access to the webhooks scope.
• For API requests, get the PEM certificate of the CA that issues your client certificates. Use the issuing CA, not the root CA.
• For webhook deliveries, prepare a CA that can sign a CSR with the clientAuth extended key usage.

Require client certificates on API requests

Each region has an mTLS endpoint. It serves the same operations as the standard endpoint and asks each client for a certificate.

API mTLS applies to HTTP API requests. It does not apply to SMTP or SIP connections. The mode does not change how those connections authenticate.

The client certificate does not replace your credential. Each request still sends an API key or service account token in the Authorization header.

The mode sets which endpoint accepts API key and service account requests. Dashboard sessions and OAuth tokens use the standard endpoint in each mode.

A valid client certificate chains to a CA of the workspace, is in its validity period and has the clientAuth extended key usage. If you set a required subject alternative name (SAN), the certificate must also contain it. We compare DNS names and URIs. We do not use the common name.

Add your certificate authority

1. Open Workspace settings > mTLS.
2. In Certificate authorities, select Add certificate authority.
3. Paste the PEM certificate of your CA, or choose a file.
4. Select Add certificate authority.

The certificate must have the CA:true basic constraint and the keyCertSign key usage, and it must not be expired. A workspace can have two CAs.

If your CA also issues certificates to other parties, set Required subject alternative name to the identity that your client certificates carry.

Test in evaluating mode

1. In Mode, select Evaluating, then select Save.
2. Configure your client to present its certificate. If an intermediate CA signs the client certificate, also send the intermediate certificate.
3. Change the base URL of your client to the mTLS endpoint.
4. Send a test request:

curl https://mtls.eu1.platform.bird.com/v1/workspace \
  --cert client.pem \
  --key client.key \
  -H "Authorization: Bearer $BIRD_API_KEY"

A response other than 401 shows that the certificate check passed. A 401 response contains an error code. Troubleshoot gives the cause of each code.

Enforce mTLS

1. Move each integration to the mTLS endpoint.
2. In Mode, select Enforced, then select Save.

The standard endpoint now rejects API key and service account requests for the workspace with E02090.

A change to the CAs or the required SAN can take up to 15 minutes to apply to each request.

Present a client certificate on webhook deliveries

We generate an RSA 2048 key pair and a CSR with the subject CN=<workspace ID>, O=Bird. The private key stays with us. Your CA signs the CSR, and we present the signed certificate when your receiver asks for one.

We present the certificate on webhook subscriptions and direct callbacks, including retries. These deliveries do not present it:

• realtime.* events
• Connector endpoints
• MCP Events subscriptions

Sign and upload the certificate

1. Open Webhooks > mTLS.
2. In Certificate, select Create signing request.
3. In Signing request, select Download.
4. Get the CSR signed by your CA with the clientAuth extended key usage.
5. Select Upload certificate.
6. Paste the signed certificate first, then each intermediate certificate in order. You can also choose a file.
7. Select Upload certificate.

We check that the certificate matches the key of the signing request, has the clientAuth extended key usage and is in its validity period. The Certificate section then shows its subject, issuer, serial number, SHA-256 fingerprint and validity period.

Configure your receivers

1. Request a client certificate during the TLS handshake.
2. Trust the CA that signed our certificate.
3. Present a server certificate from a publicly trusted CA that matches the receiver hostname.

To accept our certificate and no other certificate from your CA, match the subject CN=<workspace ID> or the SHA-256 fingerprint.

Enforce webhook mTLS

1. In Mode, select Evaluating, then select Save.
2. Send a test event to each webhook with POST /v1/webhooks/{webhook_id}/test. Make sure that client_certificate is presented. not_requested means the receiver did not ask for the certificate, and rejected means it did not accept it.
3. For SMS callback URLs, which have no webhook ID, send an SMS with options.callback_url set to the receiver. Check the logs of the receiver, and make sure that the callback presents our certificate. In evaluating, a rejected certificate also shows in GET /v1/webhook-callbacks/attempts as a failed attempt with a failure_reason.
4. In Mode, select Enforced, then select Save.

In enforced mode, a rejected certificate shows as a failed attempt in the delivery attempts of the webhook.

Check revocation

Set Certificate revocation list check to Full chain to check revocation with certificate revocation lists (CRLs).

• On API requests, we check the client certificate and each intermediate certificate below your CA.
• On webhook deliveries, we check the server certificate of your receiver and each intermediate certificate below its root.

We check each CRL distribution point of the certificate. The http and https URIs of one distribution point are mirrors of the same CRL, and we use the first mirror that responds. A distribution point without an http or https URI fails the check. A certificate without CRL distribution points is not checked. We verify the signature of each CRL. If we cannot get a valid CRL, we reject the request or fail the delivery attempt.

Rotate certificates

We email the workspace contacts 30 days and 7 days before a CA or the webhook client certificate expires.

To rotate the CA for API requests:

1. Add the new CA. The workspace now trusts both CAs.
2. Move each integration to a client certificate from the new CA.
3. Remove the old CA.

You cannot remove the last CA while the mode is evaluating or enforced. Client certificates from your CA need no action in Bird.

To rotate the webhook client certificate:

1. Select Create new signing request.
2. Get the new CSR signed and upload the certificate.

The current certificate stays in use until you upload the new one. Test sends use the new certificate at once, but deliveries can keep presenting the previous one for up to a few minutes. Your receivers must accept both certificates, by CA or by fingerprint, until then.

Automate with the API

Each dashboard action has an API operation. Send these calls to an endpoint that your mode accepts: the standard endpoint in disabled or evaluating mode, and the mTLS endpoint with a client certificate in enforced mode. The API key needs write access to the access_restrictions scope. Organization master keys cannot use them.

curl -X PATCH https://eu1.platform.bird.com/v1/workspace/mtls-settings \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"state": "enforced", "crl_check": "full_chain"}'

Troubleshoot

API requests that fail a check return 401 with one of these codes:

A setting change can return one of these codes:

• E10027: API mTLS is not enabled for the workspace. Contact your Bird representative to enable API mTLS for your organization. If it is already enabled, ask an organization administrator to raise the workspace's API mTLS limit.
• E10028: webhook mTLS is not enabled for the workspace. Contact your Bird representative to enable webhook mTLS for your organization. If it is already enabled, ask an organization administrator to raise the workspace's webhook mTLS limit.

Next steps

• Authentication: API keys, scopes and service accounts
• Webhooks & events: create endpoints and verify signatures
• Errors: the error envelope and how to handle it