# API API kluczy Te punkty końcowe umożliwiają zarządzanie kluczami API konta z poziomu kodu. Wszystkie działają wyłącznie w obrębie kluczy wywołującego konta. Istnieją dwa rodzaje kluczy, które znajdują się w oddzielnych ścieżkach: - **Twój główny klucz** — pojedynczy klucz z pełnym dostępem dostępny w sekcji **Ustawienia → Integracje → Klucz API**. Możesz sprawdzić jego zamaskowany podgląd, zweryfikować wykorzystanie limitów, zrotować go lub unieważnić. Służą do tego punkty końcowe `/api-keys/current`, `/api-keys/rotate` oraz `/api-keys/usage` poniżej. - **Klucze o ograniczonym zakresie (Scoped keys)** — dodatkowe, nazwane klucze tworzone do konkretnych zadań, z których każdy jest ograniczony do wybranych części API. Służą do tego punkty końcowe `/api-keys` oraz `/api-keys/{id}` w sekcji [Klucze o ograniczonym zakresie](#scoped-keys). Tworzenie takich kluczy nie zmienia niczego w głównym kluczu; istniejące integracje działają bez zmian. Wszystkie poniższe ścieżki są względne względem bazowego adresu URL API: ``` https://api.youraiconnector.com/v1 ``` Każde żądanie musi zostać uwierzytelnione. Zobacz [Uwierzytelnianie](authentication.md), aby poznać cztery akceptowane metody. Przykłady tutaj używają nagłówka `X-API-Key` (oraz jednej formy parametru zapytania dla cURL). > **Przeczytaj to najpierw.** Rotacja lub unieważnienie klucza wchodzi w życie **natychmiast**. W momencie, gdy którekolwiek z tych wywołań zakończy się powodzeniem, stary klucz przestaje działać — każda integracja, która go nadal używa, zacznie otrzymywać błędy `401`. Zaplanuj to: wykonaj rotację w oknie serwisowym i natychmiast zaktualizuj wszystkie swoje integracje. --- ## Pobierz metadane bieżącego klucza Zwraca aktywny klucz: pełny klucz w `api_key`, jeśli dostępna jest kopia do pobrania, zamaskowany podgląd (pierwsze 4 i ostatnie 4 znaki) oraz, jeśli jest dostępna, datę jego utworzenia. `api_key` jest `null` dla kluczy utworzonych przed wprowadzeniem przechowywania kopii do pobrania — wykonaj rotację raz, a nowy klucz będzie można ponownie wyświetlić w późniejszym czasie. `GET /api-keys/current` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Odpowiedź** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "api_key_masked": "abcd...qrst", "created_at": "2026-06-01T10:00:00.000Z" } ``` Jeśli konto nie posiada klucza API, odpowiedzią jest `404` wraz z `{ "success": false, "error": "No API key found for this account" }`. --- ## Pobierz wykorzystanie limitu zapytań Zwraca wykorzystanie limitu zapytań dla bieżącego okna: limit zapytań na okno, liczbę dotychczas wykonanych zapytań, liczbę pozostałych zapytań oraz czas resetowania okna. Użyj tego, aby zbudować mechanizm ograniczania przepustowości po stronie klienta, dzięki czemu Twoja integracja zwolni przed otrzymaniem odpowiedzi `429`. `GET /api-keys/usage` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys/usage" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", { headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.get( "https://api.youraiconnector.com/v1/api-keys/usage", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Odpowiedź** ```json { "success": true, "usage": { "limit": 300, "window_seconds": 60, "used": 37, "remaining": 263, "window_resets_at": "2026-06-09T12:01:00.000Z" } } ``` Jeśli w bieżącym oknie nie zarejestrowano jeszcze żadnych żądań, wykorzystanie jest raportowane jako zero, a odpowiedź zawiera pole `note` wyjaśniające przyczynę. --- ## Rotacja klucza Generuje nowy klucz API i jednocześnie unieważnia poprzedni. Użyj tej funkcji, jeśli podejrzewasz, że Twój klucz wyciekł, lub w ramach regularnej polityki rotacji poświadczeń. `POST /api-keys/rotate` > **Nowy klucz jest wyświetlany tylko raz.** Jest on zwracany w tej odpowiedzi i nie można go później w pełni odzyskać — przechowuj go bezpiecznie w momencie otrzymania. Poprzedni klucz przestaje działać w chwili, gdy to wywołanie zakończy się powodzeniem, więc zaktualizuj każdą integrację, która z niego korzystała. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys/rotate", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Odpowiedź** ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again." } ``` --- ## Unieważnij klucz Trwale usuwa klucz API Twojego konta. Unieważnienie jest natychmiastowe: każde kolejne żądanie korzystające z unieważnionego klucza — w tym integracje takie jak Make, Zapier lub własne skrypty — jest odrzucane z błędem `401`. Aby przywrócić dostęp do API, wygeneruj nowy klucz w ustawieniach konta po zalogowaniu się do aplikacji. `DELETE /api-keys/current` > **Tej operacji nie można cofnąć.** W przeciwieństwie do rotacji, unieważnienie nie zapewnia klucza zastępczego. Unieważniaj klucz tylko wtedy, gdy zamierzasz zatrzymać dostęp do API (na przykład w przypadku wycieku klucza, którego nie możesz natychmiast wymienić). **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" }, }); const data = await res.json(); ``` **Python** ```python import requests res = requests.delete( "https://api.youraiconnector.com/v1/api-keys/current", headers={"X-API-Key": "YOUR_API_KEY"}, ) data = res.json() ``` **Odpowiedź** ```json { "success": true, "revoked": true, "message": "API key revoked. All requests using it will be rejected immediately." } ``` Jeśli konto nie posiada klucza do unieważnienia, odpowiedzią jest `404`. --- ## Klucze o ograniczonym zakresie Klucz o ograniczonym zakresie to dodatkowy klucz API tworzony do konkretnego zadania, posiadający tylko te uprawnienia, które są do niego niezbędne. Klasyczny przykład: chcesz podłączyć pulpit nawigacyjny klienta, narzędzie raportujące lub wewnętrzny skrypt do swojego konta, nie udostępniając klucza, który mógłby również wysyłać wiadomości, zmieniać agentów AI lub kupować numery telefonów. Ograniczenie jest przypisane do samego klucza, więc każdy, kto go posiada, może wykonywać tylko te czynności, na które zezwoliłeś podczas jego tworzenia. **Co można ograniczyć** | Pole | Co oznacza | |---|---| | `read_only` | `true` (wartość domyślna) oznacza, że dozwolone są tylko żądania odczytu. Każda próba utworzenia, aktualizacji lub usunięcia zostanie odrzucona. | | `tags` | Lista sekcji API, z których klucz może korzystać, zapisana przy użyciu tych samych nazw sekcji, które widzisz w tej dokumentacji oraz w [eksploratorze API](reference.md) — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments` itd. Pusta lista oznacza wszystkie sekcje. | | `sub_account_ids` | Konta zarządzane, na których klucz może operować. Puste pole oznacza tylko Twoje własne konto; `["*"]` oznacza dowolne konto, którym faktycznie zarządzasz. Uprawnienia są sprawdzane przy każdym żądaniu. | | `rate_limit_per_min` | Liczba żądań na minutę dla tego klucza, liczona w ramach jego własnego budżetu, dzięki czemu nie zużywa on limitu innych integracji. Wartość domyślna to `60`, a maksymalna to `300`. | Możesz również nadać kluczowi datę `expires_at` (w formacie ISO 8601, musi to być data przyszła). Po tym momencie klucz przestanie działać. Jeśli pominiesz to pole, klucz nigdy nie wygaśnie, dopóki go nie unieważnisz. > **Odmowy są domyślnie bezpieczne.** Jeśli żądanie wykracza poza zakres dozwolony dla klucza, zostaje odrzucone zamiast przepuszczone: operacja zapisu przy użyciu klucza tylko do odczytu zwraca `403` z `error_code: "key_read_only"`, a wszystko poza dozwolonymi sekcjami klucza zwraca `403` z `error_code: "key_scope_denied"`. Jeśli klucz o ograniczonym zakresie otrzyma nieoczekiwany `403`, oznacza to po prostu, że wywołany punkt końcowy nie znajduje się w jego zakresie — rozszerz uprawnienia klucza lub użyj klucza głównego. > **Tylko właściciel konta zarządza kluczami.** Te cztery punkty końcowe wymagają użycia głównego klucza lub sesji właściciela w aplikacji. Klucz o ograniczonym zakresie nigdy nie może wyświetlać, tworzyć, edytować ani unieważniać kluczy — w tym samego siebie — dzięki czemu ograniczonego klucza nie można użyć do wygenerowania klucza o szerszych uprawnieniach. Próba wykonania takiej operacji zwraca `403` z `error_code: "key_scope_denied"`. Z tego samego powodu `API Keys` nie jest sekcją, którą można przyznać: próba jej uzyskania zwraca `400` z `error_code: "invalid_scopes"`. ### Wyświetlanie kluczy o ograniczonym zakresie Zwraca klucze o ograniczonym zakresie dla danego konta, od najnowszego (do 200), w tym klucze unieważnione, aby można było sprawdzić, co i kiedy zostało wycofane. Zwracane są tylko zamaskowane podglądy — wartość klucza o ograniczonym zakresie jest wyświetlana tylko raz, podczas tworzenia, i później nie można jej już odzyskać. `GET /api-keys` **cURL** ```bash curl "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" ``` **Odpowiedź** ```json { "success": true, "api_keys": [ { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } ] } ``` ### Tworzenie klucza o ograniczonym zakresie Tworzy nowy klucz o określonym zakresie i zwraca jego wartość **tylko raz**. `POST /api-keys` > **Klucz jest wyświetlany tylko raz.** Znajduje się on w tej odpowiedzi i nigdzie indziej — nie ma możliwości ponownego sprawdzenia go w późniejszym czasie. Zapisz go w momencie otrzymania. Jeśli go zgubisz, unieważnij go i utwórz nowy. **Pola treści** — wszystkie opcjonalne: | Pole | Typ | Uwagi | |---|---|---| | `label` | string | Twoja własna nazwa klucza, widoczna na liście oraz w Ustawieniach. | | `scopes` | object | Cztery pola w tabeli powyżej. Pomiń cały obiekt, aby uzyskać bezpieczne ustawienia domyślne: tylko do odczytu, ograniczone do `Analytics`, tylko dla Twojego konta, 60 żądań na minutę. | | `expires_at` | ISO 8601 date | Opcjonalna data wygaśnięcia, musi być datą przyszłą. | **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 } }' ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.com/v1/api-keys", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ label: "Client dashboard - Acme", scopes: { read_only: true, tags: ["Analytics"] }, }), }); const data = await res.json(); // Save data.api_key now — it will not be shown again. ``` **Python** ```python import requests res = requests.post( "https://api.youraiconnector.com/v1/api-keys", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "label": "Client dashboard - Acme", "scopes": {"read_only": True, "tags": ["Analytics"]}, }, ) data = res.json() # Save data["api_key"] now — it will not be shown again. ``` **Odpowiedź** — `201 Created` ```json { "success": true, "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst", "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics"], "sub_account_ids": [], "rate_limit_per_min": 60 }, "expires_at": null, "revoked": false }, "message": "Store this key now — it is shown once and cannot be retrieved again." } ``` Kilka szczegółów, które warto znać podczas tworzenia rozwiązań w oparciu o to: - **Pominięcie `scopes` nie jest tym samym, co wysłanie pustej listy `tags`.** Pomiń `scopes` całkowicie, aby uzyskać bezpieczne ustawienia domyślne (tylko do odczytu, tylko `Analytics`). Wyślij `"tags": []` celowo, a klucz będzie mógł korzystać z każdej sekcji — jest to odczytywane jako świadome żądanie klucza bez ograniczeń. - **`read_only` pozostaje `true`, chyba że jawnie wyślesz `false`.** Literówka lub brak flagi nigdy nie spowodują przypadkowego utworzenia klucza z uprawnieniami do zapisu. ### Aktualizacja klucza o określonym zakresie Zmienia etykietę, zakresy i/lub datę wygaśnięcia klucza. Wyślij dowolną kombinację tych trzech elementów; wysłanie żadnego z nich zwróci `400`. `PATCH /api-keys/{id}` `{id}` to `id` klucza z listy (wartość `key_...`), a nie sam klucz. > **Zakresy są zastępowane, a nie scalane.** Wszystko, co wyślesz, staje się pełnym zestawem uprawnień klucza. Jest to celowe: zawężenie klucza nigdy nie może pozostawić starego, szerszego dostępu w sposób niezauważony. Zawsze wysyłaj pełny obiekt `scopes`, który chcesz uzyskać, a nie tylko pole, które zmieniasz. Wartość klucza nigdy się nie zmienia. Nie ma możliwości rotacji klucza o określonym zakresie w miejscu — aby go zmienić, utwórz nowy klucz i unieważnij stary, dzięki czemu dostęp poświadczenia nigdy nie zmieni się w integracji, która go nadal posiada. **cURL** ```bash curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Client dashboard - Acme (read-only)", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 } }' ``` **Odpowiedź** ```json { "success": true, "key": { "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "label": "Client dashboard - Acme (read-only)", "key_preview": "abcd...qrst", "scopes": { "read_only": true, "tags": ["Analytics", "Campaigns"], "sub_account_ids": [], "rate_limit_per_min": 30 }, "expires_at": null, "last_used_at": "2026-08-20T14:03:00.000Z", "created_at": "2026-08-14T09:12:00.000Z", "revoked_at": null, "revoked": false } } ``` Jeśli na Twoim koncie nie ma klucza o tym identyfikatorze, odpowiedzią jest `404`. ### Unieważnij klucz o ograniczonym zakresie Unieważnienie następuje natychmiast: każde kolejne żądanie używające tego klucza zostanie odrzucone z błędem `401`. Twój główny klucz oraz wszystkie inne klucze o ograniczonym zakresie pozostają bez zmian. `DELETE /api-keys/{id}` Klucz pozostaje na Twojej liście oznaczony jako `"revoked": true`, dzięki czemu zachowujesz informację o tym, co istniało i do czego klucz miał dostęp. Unieważnienie klucza, który jest już unieważniony, kończy się powodzeniem i niczego nie zmienia. **cURL** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" ``` **Odpowiedź** ```json { "success": true, "revoked": true, "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a", "message": "API key revoked. All requests using it will be rejected immediately." } ``` --- ## Błędy API kluczy API Punkty końcowe kluczy API zwracają standardową kopertę błędu: ```json { "success": false, "error": "No API key found for this account" } ``` W przypadku punktu końcowego klucza API, brakujący lub nieprawidłowy klucz zwraca `401`, a konto bez zapisanego klucza zwraca `404`. Wspólne kody, które może zwrócić każdy punkt końcowy — `400`, `403` (Twój plan nie obejmuje dostępu do API), `429` (limit szybkości) oraz `500` — zostały wymienione wraz ze wskazówkami dotyczącymi ponawiania prób w sekcji [Błędy i stronicowanie](errors-and-pagination.md). Punkty końcowe dla kluczy o ograniczonym zakresie dodają kilka nazwanych kodów w polu `error_code`, dzięki czemu można rozróżnić poszczególne przypadki: | `error_code` | Status | Co się stało | |---|---|---| | `key_read_only` | `403` | Klucz tylko do odczytu próbował wykonać zapis. | | `key_scope_denied` | `403` | Klucz nie jest dozwolony w tym punkcie końcowym lub na tym zarządzanym koncie — lub klucz o ograniczonym zakresie próbował zarządzać kluczami API, co jest niedozwolone. | | `invalid_scopes` | `400` | Żądane zakresy obejmowały sekcję `API Keys`. Klucze nie mogą zarządzać kluczami. | | `404` | `404` | Brak klucza o tym identyfikatorze na Twoim koncie. | --- ## Następne kroki - [Uwierzytelnianie](authentication.md) — cztery sposoby uwierzytelniania żądania oraz informacje o tym, jak egzekwowane są zakresy kluczy. - [Błędy i limity szybkości](errors-and-pagination.md) — kody statusu oraz limit 300 żądań na minutę.