---
title: "mTLS"
description: "Wajibkan sertifikat klien pada permintaan API melalui endpoint mTLS, dan sajikan sertifikat klien pada pengiriman webhook ke penerima Anda."
canonical: "https://bird.com/id-id/dokumentasi/guides/mtls"
availability: "on-request"
---

# mTLS

Mutual TLS (mTLS) menambahkan pemeriksaan sertifikat ke handshake TLS di kedua arah. Setiap arah memiliki pengaturannya sendiri. Anda dapat menyiapkan satu arah atau keduanya.

| Arah               | Klien TLS   | Server TLS    | Pengaturan                                                                      |
| ------------------ | ----------- | ------------- | ------------------------------------------------------------------------------- |
| Permintaan API     | Sistem Anda | Endpoint mTLS | [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls) |
| Pengiriman webhook | Kami        | Penerima Anda | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls)           |

Setiap pihak menyimpan kunci privatnya sendiri. Untuk permintaan API, Anda memberi kami sertifikat publik dari otoritas sertifikat (CA) Anda. Untuk pengiriman webhook, kami memberi Anda permintaan penandatanganan sertifikat (CSR), lalu Anda mengembalikan sertifikat publik yang sudah ditandatangani.

## Sebelum memulai

- Hubungi perwakilan Bird Anda untuk mengaktifkan mTLS API, mTLS webhook, atau keduanya untuk organisasi Anda. Setiap arah diaktifkan secara terpisah.
- Dapatkan peran dengan akses tulis ke cakupan `access_restrictions` di workspace. Untuk mengirim peristiwa uji webhook, dapatkan juga akses tulis ke cakupan `webhooks`.
- Untuk permintaan API, dapatkan sertifikat PEM dari CA yang menerbitkan sertifikat klien Anda. Gunakan CA penerbit, bukan CA root. Pemeriksaan rantai menerima setiap sertifikat yang memiliki rantai ke CA terdaftar, sehingga CA root juga meloloskan sertifikat dari CA penerbit lain di bawahnya. Setiap sertifikat tetap harus lolos pemeriksaan lainnya, seperti extended key usage `clientAuth`.
- Untuk pengiriman webhook, siapkan CA yang dapat menandatangani CSR dengan extended key usage `clientAuth`.

## Wajibkan sertifikat klien pada permintaan API

Setiap region memiliki endpoint mTLS. Endpoint ini melayani operasi yang sama dengan endpoint standar dan meminta sertifikat dari setiap klien.

| Region | Endpoint standar                | Endpoint mTLS                        |
| ------ | ------------------------------- | ------------------------------------ |
| `eu1`  | `https://eu1.platform.bird.com` | `https://mtls.eu1.platform.bird.com` |
| `us1`  | `https://us1.platform.bird.com` | `https://mtls.us1.platform.bird.com` |

Sertifikat klien tidak menggantikan kredensial Anda. Setiap permintaan tetap mengirimkan kunci API, token OAuth, atau token akun layanan di header `Authorization`.

Mode adalah pengaturan workspace. Mode menentukan endpoint mana yang menerima permintaan untuk workspace dengan kunci API, token OAuth, atau token akun layanan.

| Mode         | Endpoint standar    | Endpoint mTLS                                                    |
| ------------ | ------------------- | ---------------------------------------------------------------- |
| `disabled`   | Menerima permintaan | Menolak permintaan                                               |
| `evaluating` | Menerima permintaan | Menerima permintaan yang menyertakan sertifikat klien yang valid |
| `enforced`   | Menolak permintaan  | Menerima permintaan yang menyertakan sertifikat klien yang valid |

Mode berlaku untuk lalu lintas berikut. Semua lalu lintas lain tetap berfungsi di setiap mode.

| Lalu lintas                                                           | Mode `enforced`                                                                                              |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Permintaan API dengan kunci API, token OAuth, atau token akun layanan | Endpoint standar menolaknya dengan [`E02090`](/docs/api/errors/E02090).                                      |
| Pengiriman [SMTP](/docs/guides/email/smtp)                            | Ditolak. SMTP tidak dapat menyajikan sertifikat klien.                                                       |
| Server MCP yang di-host                                               | Tidak dapat menjangkau workspace. Server ini tidak dapat menyajikan sertifikat klien Anda.                   |
| Sesi dasbor                                                           | Tidak terpengaruh.                                                                                           |
| Automations                                                           | Tidak terpengaruh.                                                                                           |
| Permintaan dengan kredensial organisasi pada operasi organisasi       | Tidak diperiksa. Mode dimiliki oleh workspace, sedangkan permintaan ini tidak menyebutkan workspace apa pun. |
| [Trunk SIP](/docs/guides/voice/sip-trunks)                            | Tidak terpengaruh. Trunk tetap mengautentikasi panggilan dengan kunci API yang diizinkan, tanpa sertifikat.  |

Perubahan mode langsung berlaku untuk permintaan baru. Sesi SMTP yang sedang terbuka menerapkan mode baru pada pesan berikutnya.

Sertifikat klien yang valid memiliki rantai ke CA milik workspace, masih dalam masa berlakunya, dan memiliki extended key usage `clientAuth`. Jika Anda menetapkan subject alternative name (SAN) wajib, sertifikat juga harus memuatnya. Kami membandingkan nama DNS dan URI. Kami tidak menggunakan common name.

### Tambahkan otoritas sertifikat Anda

1. Buka [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls).
2. Di **Certificate authorities**, pilih **Add certificate authority**.
3. Tempelkan sertifikat PEM dari CA Anda, atau pilih file.
4. Pilih **Add certificate authority**.

Sertifikat harus memiliki basic constraint `CA:true` dan key usage `keyCertSign`, serta tidak boleh kedaluwarsa. Satu workspace dapat memiliki dua CA.

Jika CA Anda juga menerbitkan sertifikat untuk pihak lain, atur **Required subject alternative name** ke identitas yang dimuat sertifikat klien Anda.

### Uji dalam mode evaluasi

1. Di **Mode**, pilih **Evaluating**, lalu pilih **Save**.
2. Konfigurasikan klien Anda agar menyajikan sertifikatnya. Jika CA perantara menandatangani sertifikat klien, kirim juga sertifikat perantara tersebut.
3. Ubah URL dasar klien Anda ke endpoint mTLS.
4. Kirim permintaan uji:

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

Respons selain `401` menunjukkan bahwa pemeriksaan sertifikat berhasil. Respons `401` berisi kode kesalahan. [Pemecahan masalah](#pemecahan-masalah) menjelaskan penyebab setiap kode.

Untuk menemukan pemanggil yang akan ditolak oleh mode `enforced`, filter log permintaan workspace berdasarkan **mTLS** `missing`. Log permintaan mencatat operasi tulis, seperti permintaan `POST`, `PATCH`, dan `DELETE`, serta pengiriman SMTP. Log ini tidak mencatat operasi baca, jadi periksa secara terpisah klien yang hanya membaca, karena mode `enforced` juga menolaknya.

### Terapkan mTLS secara wajib

1. Pindahkan setiap integrasi ke endpoint mTLS.
2. Di **Mode**, pilih **Enforced**, lalu pilih **Save**.

Endpoint standar kini menolak permintaan dengan kunci API, token OAuth, atau token akun layanan untuk workspace tersebut dengan [`E02090`](/docs/api/errors/E02090).

Server MCP yang di-host tidak dapat menjangkau workspace. Sebagai gantinya, gunakan server MCP lokal dari [Bird CLI](#gunakan-bird-cli).

Endpoint SMTP menolak AUTH untuk workspace dengan `535 5.7.8`. Sesi SMTP yang sedang terbuka menerima `530 5.7.0` pada pesan berikutnya. Sebagai gantinya, kirim email melalui API di endpoint mTLS.

Perubahan pada CA atau SAN wajib dapat memerlukan waktu hingga 15 menit sebelum berlaku untuk setiap permintaan.

### Gunakan Bird CLI

[Bird CLI](/docs/cli) dan server MCP lokalnya (`bird mcp`) menyajikan sertifikat klien Anda dengan pengaturan berikut:

| Pengaturan                                              | Flag            | Variabel lingkungan |
| ------------------------------------------------------- | --------------- | ------------------- |
| Rantai sertifikat, PEM, sertifikat leaf terlebih dahulu | `--client-cert` | `BIRD_CLIENT_CERT`  |
| Kunci privat, PEM, tidak terenkripsi                    | `--client-key`  | `BIRD_CLIENT_KEY`   |
| Kirim permintaan ke endpoint mTLS                       | `--mtls`        | `BIRD_MTLS=1`       |

```bash
export BIRD_API_KEY=bk_eu1_...
export BIRD_CLIENT_CERT=client.pem
export BIRD_CLIENT_KEY=client.key
bird workspace get --mtls
```

Agar pengaturan tetap tersimpan dengan login OAuth, berikan ketiga flag tersebut ke `bird auth login`. Profil menyimpan path file, dan perintah berikutnya menggunakan endpoint mTLS tanpa flag. `bird auth status` menampilkan sidik jari SHA-256 dan kedaluwarsa sertifikat.

### Gunakan SDK

Berikan path rantai sertifikat Anda (PEM, sertifikat leaf terlebih dahulu) dan kunci privatnya (PEM, tidak terenkripsi) kepada SDK. SDK menyajikan sertifikat pada setiap permintaan dan mengirim permintaan ke endpoint mTLS di region kunci API Anda. Jika Anda menetapkan URL dasar, SDK menggunakan URL tersebut.

SDK menolak sertifikat yang diberikan bersama klien HTTP milik Anda sendiri. Untuk menggunakan klien HTTP Anda sendiri, konfigurasikan sertifikat pada klien tersebut dan tetapkan URL dasar ke endpoint mTLS.

**TypeScript**

```typescript
// Node.js only. Install the optional undici dependency if your package manager skipped it.
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY!,
  clientCertificate: { cert: "client.pem", key: "client.key" },
});

const workspace = await bird.workspace.get();
console.log(workspace.id);
```

Examples: [TypeScript](/id-id/dokumentasi/guides/mtls.ts.md) · [Python](/id-id/dokumentasi/guides/mtls.py.md) · [Go](/id-id/dokumentasi/guides/mtls.go.md) · [PHP](/id-id/dokumentasi/guides/mtls.php.md)

## Sajikan sertifikat klien pada pengiriman webhook

Kami membuat pasangan kunci RSA 2048 dan CSR dengan subjek `CN=<workspace ID>, O=Bird`. Kunci privat tetap berada di pihak kami. CA Anda menandatangani CSR tersebut, dan kami menyajikan sertifikat yang telah ditandatangani saat penerima Anda memintanya.

Kami menyajikan sertifikat pada langganan webhook dan callback langsung, termasuk saat coba lagi. Pengiriman berikut tidak menyajikannya:

- Peristiwa `realtime.*`
- Endpoint konektor
- Langganan MCP Events

| Mode         | Perilaku pengiriman                                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `disabled`   | Kami tidak menyajikan sertifikat.                                                                                    |
| `evaluating` | Kami menyajikan sertifikat saat penerima memintanya. Jika penerima menolaknya, kami mengirim ulang tanpa sertifikat. |
| `enforced`   | Kami menyajikan sertifikat. Jika penerima tidak memintanya atau menolaknya, upaya pengiriman gagal.                  |

### Tandatangani dan unggah sertifikat

1. Buka [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls).
2. Di **Certificate**, pilih **Create signing request**.
3. Di **Signing request**, pilih **Download**.
4. Minta CA Anda menandatangani CSR dengan extended key usage `clientAuth`.
5. Pilih **Upload certificate**.
6. Tempelkan sertifikat yang sudah ditandatangani terlebih dahulu, lalu setiap sertifikat perantara secara berurutan. Anda juga dapat memilih file.
7. Pilih **Upload certificate**.

Kami memeriksa bahwa sertifikat cocok dengan kunci dari permintaan penandatanganan, memiliki extended key usage `clientAuth`, dan berada dalam masa berlakunya. Bagian **Certificate** kemudian menampilkan subjek, penerbit, nomor seri, sidik jari SHA-256, dan masa berlakunya.

### Konfigurasikan penerima Anda

1. Minta sertifikat klien selama handshake TLS.
2. Percayai CA yang menandatangani sertifikat kami.
3. Tunjukkan sertifikat server dari CA tepercaya publik yang cocok dengan hostname penerima.

Untuk menerima sertifikat kami dan menolak sertifikat lain dari CA Anda, cocokkan subjek `CN=<workspace ID>` atau sidik jari SHA-256.

### Terapkan mTLS webhook

1. Di **Mode**, pilih **Evaluating**, lalu pilih **Save**.
2. Kirim event uji ke setiap webhook dengan [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook). Pastikan `client_certificate` bernilai `presented`. `not_requested` berarti penerima tidak meminta sertifikat, dan `rejected` berarti penerima tidak menerimanya.
3. Untuk [URL callback SMS](/docs/guides/sms/callbacks), yang tidak memiliki ID webhook, kirim SMS dengan `options.callback_url` diatur ke penerima. Periksa log penerima, dan pastikan callback menyajikan sertifikat kami. Dalam mode `evaluating`, sertifikat yang ditolak juga muncul di [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) sebagai percobaan gagal dengan `failure_reason`.
4. Di **Mode**, pilih **Enforced**, lalu pilih **Save**.

Dalam mode `enforced`, sertifikat yang ditolak muncul sebagai percobaan gagal di [percobaan pengiriman](/docs/guides/webhooks#replaying-failed-deliveries) webhook tersebut.

## Memeriksa pencabutan

Atur **Certificate revocation list check** ke **Full chain** untuk memeriksa pencabutan dengan daftar pencabutan sertifikat (CRL).

- Pada permintaan API, kami memeriksa sertifikat klien dan setiap sertifikat perantara di bawah CA Anda.
- Pada pengiriman webhook, kami memeriksa sertifikat server penerima Anda dan setiap sertifikat perantara di bawah root-nya.

Kami memeriksa setiap titik distribusi CRL pada sertifikat. URI `http` dan `https` dari satu titik distribusi adalah mirror dari CRL yang sama, dan kami menggunakan mirror pertama yang merespons. Titik distribusi tanpa URI `http` atau `https` gagal dalam pemeriksaan. Sertifikat tanpa titik distribusi CRL tidak diperiksa. Kami memverifikasi tanda tangan setiap CRL. Jika kami tidak bisa mendapatkan CRL yang valid, kami menolak permintaan atau menggagalkan percobaan pengiriman.

| Batas                      | Nilai                                                          |
| -------------------------- | -------------------------------------------------------------- |
| Waktu unduh CRL            | 5 detik untuk setiap unduhan, 10 detik untuk setiap permintaan |
| Ukuran CRL                 | 10 MiB                                                         |
| CRL untuk setiap workspace | 10 untuk permintaan API dan 10 untuk pengiriman webhook        |

## Merotasi sertifikat

Kami mengirim email kepada kontak workspace 30 hari dan 7 hari sebelum CA atau sertifikat klien webhook kedaluwarsa.

Untuk merotasi CA bagi permintaan API:

1. Tambahkan CA baru. Workspace kini memercayai kedua CA.
2. Pindahkan setiap integrasi ke sertifikat klien dari CA baru.
3. Hapus CA lama.

Anda tidak dapat menghapus CA terakhir selama mode adalah `evaluating` atau `enforced`. Sertifikat klien dari CA Anda tidak memerlukan tindakan apa pun dalam mode Bird.

Untuk merotasi sertifikat klien webhook:

1. Pilih **Create new signing request**.
2. Minta CSR baru ditandatangani, lalu unggah sertifikatnya.

Sertifikat saat ini tetap digunakan sampai Anda mengunggah sertifikat baru. Pengiriman uji langsung menggunakan sertifikat baru, tetapi pengiriman biasa dapat tetap menyajikan sertifikat sebelumnya hingga beberapa menit. Hingga saat itu, penerima Anda harus menerima kedua sertifikat, berdasarkan CA atau sidik jari.

## Otomatiskan dengan API

Setiap tindakan di dasbor memiliki operasi API. Kirim panggilan ini ke endpoint yang diterima oleh mode Anda: endpoint standar dalam mode `disabled` atau `evaluating`, dan endpoint mTLS dengan sertifikat klien dalam mode `enforced`. Kunci API memerlukan akses tulis ke cakupan `access_restrictions`. Kunci master organisasi tidak dapat menggunakan operasi ini.

| Operasi                                                                                                                                            | Tindakan                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings)                                                          | Mengubah `state`, `expected_san`, atau `crl_check` |
| [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority)                               | Menambahkan CA                                     |
| [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority)  | Menghapus CA                                       |
| [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate)                                | Mengubah `state` atau `crl_check`                  |
| [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Membuat CSR                                        |
| [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate)                     | Mengunggah sertifikat yang telah ditandatangani    |

```bash
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"}'
```

## Pemecahan masalah

Permintaan API yang gagal dalam pemeriksaan mengembalikan `401` dengan salah satu kode berikut:

| Kode                                | Penyebab                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| [`E02086`](/docs/api/errors/E02086) | Permintaan tidak menyertakan sertifikat klien.                                 |
| [`E02087`](/docs/api/errors/E02087) | Sertifikat klien tidak valid untuk workspace.                                  |
| [`E02088`](/docs/api/errors/E02088) | Salah satu sertifikat dalam rantai telah dicabut.                              |
| [`E02089`](/docs/api/errors/E02089) | Mode diatur ke `disabled`, sehingga endpoint mTLS menolak permintaan.          |
| [`E02090`](/docs/api/errors/E02090) | Mode diatur ke `enforced`, sehingga endpoint standar menolak permintaan.       |
| [`E02091`](/docs/api/errors/E02091) | Kami tidak dapat mengunduh CRL dalam 5 detik.                                  |
| [`E02092`](/docs/api/errors/E02092) | Ukuran CRL lebih dari 10 MiB.                                                  |
| [`E02093`](/docs/api/errors/E02093) | Workspace sudah menggunakan 10 CRL.                                            |
| [`E02094`](/docs/api/errors/E02094) | Tanda tangan CRL tidak valid, atau waktu pembaruan berikutnya sudah terlewati. |

Perubahan pengaturan dapat mengembalikan salah satu kode berikut:

- [`E10027`](/docs/api/errors/E10027): mTLS API belum diaktifkan untuk workspace. Hubungi perwakilan Bird Anda untuk mengaktifkannya.
- [`E10028`](/docs/api/errors/E10028): mTLS webhook belum diaktifkan untuk workspace. Hubungi perwakilan Bird Anda untuk mengaktifkannya.

## Langkah berikutnya

- [Autentikasi](/docs/guides/authentication): kunci API, cakupan, dan akun layanan
- [Webhook & event](/docs/guides/webhooks): membuat endpoint dan memverifikasi tanda tangan
- [Error](/docs/guides/errors): respons kesalahan dan cara menanganinya

## Related resources

- [Webhooks done right: reliable delivery events](/learn/basics/webhooks-done-right-reliable-delivery-events) (video)
- [How do I verify a webhook signature?](/explained/platform/how-do-i-verify-a-webhook-signature) (answer)
- [SMTP relay](/email-api/features/smtp) (product)
- [Operate messaging reliably](/learn/paths/reliability) (course)
