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. 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, 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

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "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

curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "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

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

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

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ź

{
  "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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"

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

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Odpowiedź

{
  "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ć

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

curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

Odpowiedź

{
  "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:

cURL

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

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

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

{
  "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

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ź

{
  "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

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"

Odpowiedź

{
  "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:

{
  "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.

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:

Następne kroki #

• Uwierzytelnianie — cztery sposoby uwierzytelniania żądania oraz informacje o tym, jak egzekwowane są zakresy kluczy.
• Błędy i limity szybkości — kody statusu oraz limit 300 żądań na minutę.