---
title: "mTLS"
description: "Wymagaj certyfikatu klienta w żądaniach API wysyłanych do punktu końcowego mTLS i przedstawiaj certyfikat klienta przy dostarczaniu webhooków do swoich odbiorców."
canonical: "https://bird.com/pl-pl/dokumentacja/guides/mtls"
availability: "on-request"
---

# mTLS

Wzajemny TLS (mTLS) dodaje do uzgadniania TLS sprawdzanie certyfikatu w obu kierunkach. Każdy kierunek ma własne ustawienia. Możesz skonfigurować jeden kierunek lub oba.

| Kierunek               | Klient TLS    | Serwer TLS         | Ustawienia                                                                      |
| ---------------------- | ------------- | ------------------ | ------------------------------------------------------------------------------- |
| Żądania API            | Twoje systemy | Punkt końcowy mTLS | [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls) |
| Dostarczanie webhooków | My            | Twoje odbiorniki   | [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls)           |

Każda strona przechowuje własne klucze prywatne. W przypadku żądań API przekazujesz nam publiczny certyfikat swojego urzędu certyfikacji (CA). W przypadku dostarczania webhooków przekazujemy Ci żądanie podpisania certyfikatu (CSR), a Ty odsyłasz podpisany certyfikat publiczny.

## Zanim zaczniesz

- Skontaktuj się z przedstawicielem Bird, aby włączyć dla swojej organizacji mTLS dla API, mTLS dla webhooków lub oba. Każdy kierunek włącza się osobno.
- Uzyskaj w obszarze roboczym rolę z uprawnieniami zapisu w zakresie `access_restrictions`. Aby wysyłać testowe zdarzenia webhooków, uzyskaj też uprawnienia zapisu w zakresie `webhooks`.
- W przypadku żądań API pobierz certyfikat PEM urzędu certyfikacji, który wystawia Twoje certyfikaty klienta. Wybierz urząd wystawiający zamiast głównego urzędu certyfikacji: sprawdzanie łańcucha akceptuje każdy certyfikat, którego łańcuch prowadzi do zarejestrowanego urzędu certyfikacji, więc główny urząd certyfikacji przepuszcza też certyfikaty swoich pozostałych urzędów wystawiających. Każdy certyfikat musi nadal przejść pozostałe sprawdzenia, na przykład rozszerzonego użycia klucza `clientAuth`.
- W przypadku dostarczania webhooków przygotuj urząd certyfikacji, który może podpisać CSR z rozszerzonym użyciem klucza `clientAuth`.

## Wymagaj certyfikatów klienta w żądaniach API

Każdy region ma endpoint mTLS. Obsługuje on te same operacje co endpoint standardowy i żąda certyfikatu od każdego klienta.

| Region | Standardowy endpoint            | 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` |

Certyfikat klienta nie zastępuje Twoich danych uwierzytelniających. Każde żądanie nadal wysyła klucz API, token OAuth lub token konta usługi w nagłówku `Authorization`.

Tryb jest ustawieniem obszaru roboczego. Określa, który endpoint akceptuje żądania dla obszaru roboczego z kluczem API, tokenem OAuth lub tokenem konta usługi.

| Tryb         | Standardowy endpoint | Endpoint mTLS                                   |
| ------------ | -------------------- | ----------------------------------------------- |
| `disabled`   | Akceptuje żądania    | Odrzuca żądania                                 |
| `evaluating` | Akceptuje żądania    | Akceptuje żądania z ważnym certyfikatem klienta |
| `enforced`   | Odrzuca żądania      | Akceptuje żądania z ważnym certyfikatem klienta |

Tryb dotyczy tego ruchu. Wszystko inne działa dalej w każdym trybie.

| Ruch                                                                      | Tryb `enforced`                                                                                       |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Żądania API z kluczem API, tokenem OAuth lub tokenem konta usługi         | Standardowy endpoint odrzuca je, zwracając [`E02090`](/docs/api/errors/E02090).                       |
| Wysyłanie przez [SMTP](/docs/guides/email/smtp)                           | Odrzucane. SMTP nie może przedstawić certyfikatu klienta.                                             |
| Hostowany serwer MCP                                                      | Nie ma dostępu do obszaru roboczego. Nie może przedstawić Twojego certyfikatu klienta.                |
| Sesje panelu                                                              | Bez wpływu.                                                                                           |
| Automations                                                               | Bez zmian.                                                                                            |
| Żądania z danymi uwierzytelniającymi organizacji w operacjach organizacji | Niesprawdzane. Tryb należy do obszaru roboczego, a te żądania nie wskazują żadnego obszaru roboczego. |
| [Trunki SIP](/docs/guides/voice/sip-trunks)                               | Bez zmian. Trunk nadal uwierzytelnia połączenia dozwolonym kluczem API, bez certyfikatu.              |

Zmiana trybu od razu obowiązuje dla nowych żądań. Otwarta sesja SMTP przechodzi na nowy tryb przy następnej wiadomości.

Prawidłowy certyfikat klienta tworzy łańcuch do urzędu certyfikacji obszaru roboczego, jest w okresie ważności i ma rozszerzone użycie klucza `clientAuth`. Jeśli ustawisz wymaganą alternatywną nazwę podmiotu (SAN), certyfikat musi ją również zawierać. Porównujemy nazwy DNS i identyfikatory URI. Nie używamy nazwy pospolitej (CN).

### Dodaj urząd certyfikacji

1. Otwórz [**Workspace settings** > **mTLS**](https://bird.com/dashboard/w/settings/mtls).
2. W sekcji **Certificate authorities** wybierz **Add certificate authority**.
3. Wklej certyfikat PEM swojego urzędu certyfikacji lub wybierz plik.
4. Wybierz **Add certificate authority**.

Certyfikat musi mieć ograniczenie podstawowe `CA:true` i użycie klucza `keyCertSign` oraz nie może być wygasły. Obszar roboczy może mieć dwa urzędy certyfikacji.

Jeśli Twój urząd certyfikacji wystawia certyfikaty również innym podmiotom, ustaw w polu **Required subject alternative name** tożsamość zawartą w Twoich certyfikatach klienta.

### Przetestuj w trybie ewaluacji

1. W polu **Mode** wybierz **Evaluating**, a następnie wybierz **Save**.
2. Skonfiguruj klienta tak, aby przedstawiał swój certyfikat. Jeśli certyfikat klienta podpisuje pośredni urząd certyfikacji, wysyłaj również certyfikat pośredni.
3. Zmień bazowy adres URL klienta na endpoint mTLS.
4. Wyślij żądanie testowe:

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

Odpowiedź inna niż `401` oznacza, że sprawdzenie certyfikatu się powiodło. Odpowiedź `401` zawiera kod błędu. Przyczynę każdego kodu podaje sekcja [Rozwiązywanie problemów](#rozwiązywanie-problemów).

Aby znaleźć wywołujących, których odrzuciłby tryb `enforced`, przefiltruj logi żądań obszaru roboczego według **mTLS** `missing`. Logi żądań rejestrują zapisy, takie jak żądania `POST`, `PATCH` i `DELETE`, oraz wysyłki SMTP. Nie rejestrują odczytów, więc klientów, którzy tylko odczytują dane, sprawdź osobno: tryb `enforced` również ich odrzuca.

### Wymuś mTLS

1. Przenieś każdą integrację na endpoint mTLS.
2. W polu **Mode** wybierz **Enforced**, a następnie wybierz **Save**.

Standardowy endpoint odrzuca teraz żądania z kluczem API, tokenem OAuth lub tokenem konta usługi dla tego obszaru roboczego, zwracając [`E02090`](/docs/api/errors/E02090).

Hostowany serwer MCP nie ma dostępu do obszaru roboczego. Zamiast niego użyj lokalnego serwera MCP z [Bird CLI](#korzystanie-z-bird-cli).

Endpoint SMTP odmawia AUTH dla obszaru roboczego, zwracając `535 5.7.8`. Otwarta sesja SMTP otrzymuje `530 5.7.0` przy następnej wiadomości. Zamiast tego wysyłaj e-maile przez API na endpoincie mTLS.

Zastosowanie zmiany urzędów certyfikacji lub wymaganej nazwy SAN do każdego żądania może potrwać do 15 minut.

### Korzystanie z Bird CLI

[Bird CLI](/docs/cli) i jego lokalny serwer MCP (`bird mcp`) przedstawiają Twój certyfikat klienta na podstawie tych ustawień:

| Ustawienie                                             | Flaga           | Zmienna środowiskowa |
| ------------------------------------------------------ | --------------- | -------------------- |
| Łańcuch certyfikatów, PEM, najpierw certyfikat końcowy | `--client-cert` | `BIRD_CLIENT_CERT`   |
| Klucz prywatny, PEM, niezaszyfrowany                   | `--client-key`  | `BIRD_CLIENT_KEY`    |
| Wysyłanie żądań do endpointu 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
```

Aby zachować te ustawienia przy logowaniu OAuth, przekaż trzy flagi do `bird auth login`. Profil zapisuje ścieżki plików, a kolejne polecenia używają endpointu mTLS bez flag. `bird auth status` pokazuje odcisk SHA-256 i datę wygaśnięcia certyfikatu.

### Korzystanie z SDK

Przekaż do SDK ścieżki łańcucha certyfikatów (PEM, najpierw certyfikat końcowy) i jego klucza prywatnego (PEM, niezaszyfrowany). SDK przedstawia certyfikat przy każdym żądaniu i wysyła żądania do endpointu mTLS regionu Twojego klucza API. Jeśli ustawisz bazowy adres URL, SDK używa tego adresu URL.

SDK odrzuca certyfikat podany razem z klientem HTTP, który dostarczasz samodzielnie. Aby korzystać z własnego klienta HTTP, skonfiguruj certyfikat w tym kliencie i ustaw bazowy adres URL na 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](/pl-pl/dokumentacja/guides/mtls.ts.md) · [Python](/pl-pl/dokumentacja/guides/mtls.py.md) · [Go](/pl-pl/dokumentacja/guides/mtls.go.md) · [PHP](/pl-pl/dokumentacja/guides/mtls.php.md)

## Przedstawianie certyfikatu klienta przy dostarczaniu webhooków

Generujemy parę kluczy RSA 2048 i CSR z podmiotem `CN=<workspace ID>, O=Bird`. Klucz prywatny pozostaje u nas. Twój urząd certyfikacji podpisuje CSR, a my przedstawiamy podpisany certyfikat, gdy Twój odbiornik o niego poprosi.

Przedstawiamy certyfikat w subskrypcjach webhooków i bezpośrednich wywołaniach zwrotnych, łącznie z ponownymi próbami. Następujące dostarczenia go nie przedstawiają:

- Zdarzenia `realtime.*`
- Endpointy konektorów
- Subskrypcje MCP Events

| Tryb         | Sposób dostarczania                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `disabled`   | Nie przedstawiamy certyfikatu.                                                                                             |
| `evaluating` | Przedstawiamy certyfikat, gdy odbiorca o niego poprosi. Jeśli odbiorca go odrzuci, dostarczamy ponownie bez certyfikatu.   |
| `enforced`   | Przedstawiamy certyfikat. Jeśli odbiorca o niego nie poprosi lub go odrzuci, próba dostarczenia kończy się niepowodzeniem. |

### Podpisz i prześlij certyfikat

1. Otwórz [**Webhooks** > **mTLS**](https://bird.com/dashboard/w/webhooks/mtls).
2. W sekcji **Certificate** wybierz **Create signing request**.
3. W sekcji **Signing request** wybierz **Download**.
4. Podpisz CSR swoim CA z rozszerzonym użyciem klucza `clientAuth`.
5. Wybierz **Upload certificate**.
6. Wklej najpierw podpisany certyfikat, a potem kolejno każdy certyfikat pośredni. Możesz też wybrać plik.
7. Wybierz **Upload certificate**.

Sprawdzamy, czy certyfikat pasuje do klucza z żądania podpisania, ma rozszerzone użycie klucza `clientAuth` i jest w okresie ważności. Sekcja **Certificate** pokazuje wtedy jego podmiot, wystawcę, numer seryjny, odcisk SHA-256 i okres ważności.

### Skonfiguruj odbiorniki

1. Żądaj certyfikatu klienta podczas uzgadniania TLS.
2. Ustaw zaufanie do CA, które podpisało nasz certyfikat.
3. Przedstawiaj certyfikat serwera od publicznie zaufanego CA, zgodny z nazwą hosta odbiornika.

Aby akceptować nasz certyfikat i żaden inny certyfikat od swojego CA, dopasowuj podmiot `CN=<workspace ID>` lub odcisk SHA-256.

### Wymuś mTLS dla webhooków

1. W polu **Mode** wybierz **Evaluating**, a następnie wybierz **Save**.
2. Wyślij zdarzenie testowe do każdego webhooka za pomocą [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook). Sprawdź, czy `client_certificate` ma wartość `presented`. `not_requested` oznacza, że odbiorca nie zażądał certyfikatu, a `rejected` oznacza, że go nie zaakceptował.
3. W przypadku [adresów URL wywołań zwrotnych SMS](/docs/guides/sms/callbacks), które nie mają identyfikatora webhooka, wyślij SMS z `options.callback_url` ustawionym na odbiorcę. Sprawdź logi odbiorcy i upewnij się, że wywołanie zwrotne przedstawia nasz certyfikat. W trybie `evaluating` odrzucony certyfikat jest też widoczny w [`GET /v1/webhook-callbacks/attempts`](/docs/api/reference/list-webhook-callback-attempts) jako nieudana próba z `failure_reason`.
4. W polu **Mode** wybierz **Enforced**, a następnie wybierz **Save**.

W trybie `enforced` odrzucony certyfikat jest widoczny jako nieudana próba w [próbach dostarczenia](/docs/guides/webhooks#replaying-failed-deliveries) webhooka.

## Sprawdzanie unieważnienia

Aby sprawdzać unieważnienie za pomocą list unieważnionych certyfikatów (CRL), ustaw **Certificate revocation list check** na **Full chain**.

- W żądaniach API sprawdzamy certyfikat klienta i każdy certyfikat pośredni poniżej Twojego CA.
- Przy dostarczaniu webhooków sprawdzamy certyfikat serwera Twojego odbiorcy i każdy certyfikat pośredni poniżej jego certyfikatu głównego.

Sprawdzamy każdy punkt dystrybucji CRL certyfikatu. Adresy URI `http` i `https` jednego punktu dystrybucji są kopiami tej samej listy CRL, a my używamy pierwszej kopii, która odpowie. Punkt dystrybucji bez adresu URI `http` ani `https` nie przechodzi sprawdzenia. Certyfikat bez punktów dystrybucji CRL nie jest sprawdzany. Weryfikujemy podpis każdej listy CRL. Jeśli nie możemy pobrać prawidłowej listy CRL, odrzucamy żądanie lub próba dostarczenia kończy się niepowodzeniem.

| Limit                        | Wartość                                                |
| ---------------------------- | ------------------------------------------------------ |
| Czas pobierania CRL          | 5 sekund na każde pobranie, 10 sekund na każde żądanie |
| Rozmiar CRL                  | 10 MiB                                                 |
| Liczba CRL na obszar roboczy | 10 dla żądań API i 10 dla dostarczania webhooków       |

## Rotacja certyfikatów

Wysyłamy e-mail do kontaktów obszaru roboczego 30 dni i 7 dni przed wygaśnięciem CA lub certyfikatu klienta webhooków.

Aby wymienić CA dla żądań API:

1. Dodaj nowe CA. Obszar roboczy ufa wtedy obu CA.
2. Przenieś każdą integrację na certyfikat klienta wystawiony przez nowe CA.
3. Usuń stare CA.

Nie możesz usunąć ostatniego CA, gdy tryb to `evaluating` lub `enforced`. Certyfikaty klienta wystawione przez Twoje CA nie wymagają żadnych działań w trybie Bird.

Aby wymienić certyfikat klienta dla webhooków:

1. Wybierz **Create new signing request**.
2. Podpisz nowy CSR i prześlij certyfikat.

Bieżący certyfikat pozostaje w użyciu, dopóki nie prześlesz nowego. Testowe wysyłki od razu używają nowego certyfikatu, ale dostarczenia mogą jeszcze przez kilka minut przedstawiać poprzedni. Do tego czasu Twoje odbiorniki muszą akceptować oba certyfikaty, na podstawie CA lub odcisku.

## Automatyzacja za pomocą API

Każdej akcji w panelu odpowiada operacja API. Wysyłaj te wywołania do punktu końcowego, który akceptuje Twój tryb: do standardowego punktu końcowego w trybie `disabled` lub `evaluating`, a do punktu końcowego mTLS z certyfikatem klienta w trybie `enforced`. Klucz API wymaga uprawnień do zapisu w zakresie `access_restrictions`. Klucze główne organizacji nie mogą korzystać z tych operacji.

| Operacja                                                                                                                                           | Akcja                                          |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [`PATCH /v1/workspace/mtls-settings`](/docs/api/reference/update-workspace-mtls-settings)                                                          | Zmiana `state`, `expected_san` lub `crl_check` |
| [`POST /v1/workspace/mtls-certificate-authorities`](/docs/api/reference/create-workspace-mtls-certificate-authority)                               | Dodaj urząd certyfikacji                       |
| [`DELETE /v1/workspace/mtls-certificate-authorities/{certificate_authority_id}`](/docs/api/reference/delete-workspace-mtls-certificate-authority)  | Usuń urząd certyfikacji                        |
| [`PATCH /v1/workspace/webhook-client-certificate`](/docs/api/reference/update-workspace-webhook-client-certificate)                                | Zmień `state` lub `crl_check`                  |
| [`POST /v1/workspace/webhook-client-certificate/signing-request`](/docs/api/reference/create-workspace-webhook-client-certificate-signing-request) | Utwórz CSR                                     |
| [`POST /v1/workspace/webhook-client-certificate/certificate`](/docs/api/reference/submit-workspace-webhook-client-certificate)                     | Prześlij podpisany certyfikat                  |

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

## Rozwiązywanie problemów

Żądania API, które nie przejdą sprawdzenia, zwracają `401` z jednym z tych kodów:

| Kod                                 | Przyczyna                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| [`E02086`](/docs/api/errors/E02086) | Żądanie nie przedstawiło certyfikatu klienta.                                  |
| [`E02087`](/docs/api/errors/E02087) | Certyfikat klienta nie jest ważny dla obszaru roboczego.                       |
| [`E02088`](/docs/api/errors/E02088) | Jeden z certyfikatów w łańcuchu został unieważniony.                           |
| [`E02089`](/docs/api/errors/E02089) | Tryb to `disabled`, więc punkt końcowy mTLS odrzuca żądanie.                   |
| [`E02090`](/docs/api/errors/E02090) | Tryb to `enforced`, więc standardowy punkt końcowy odrzuca żądanie.            |
| [`E02091`](/docs/api/errors/E02091) | Nie udało nam się pobrać listy CRL w ciągu 5 sekund.                           |
| [`E02092`](/docs/api/errors/E02092) | Lista CRL jest większa niż 10 MiB.                                             |
| [`E02093`](/docs/api/errors/E02093) | Obszar roboczy używa już 10 list CRL.                                          |
| [`E02094`](/docs/api/errors/E02094) | Lista CRL ma nieprawidłowy podpis lub minął termin jej następnej aktualizacji. |

Zmiana ustawienia może zwrócić jeden z tych kodów:

- [`E10027`](/docs/api/errors/E10027): mTLS dla API nie jest włączone w obszarze roboczym. Skontaktuj się z przedstawicielem Bird, aby je włączyć.
- [`E10028`](/docs/api/errors/E10028): mTLS dla webhooków nie jest włączone w obszarze roboczym. Skontaktuj się z przedstawicielem Bird, aby je włączyć.

## Następne kroki

- [Uwierzytelnianie](/docs/guides/authentication): klucze API, zakresy i konta usług
- [Webhooki i zdarzenia](/docs/guides/webhooks): tworzenie punktów końcowych i weryfikacja podpisów
- [Błędy](/docs/guides/errors): odpowiedź z błędem i sposób jej obsługi

## 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)
