Your AI Connector Docs

Uwierzytelnianie

Każde żądanie API musi zawierać Twój klucz API, aby Your AI Connector wiedziało, że to Ty i na którym koncie ma wykonać operację. Klucz możesz przesłać na cztery różne sposoby — wszystkie działają w każdym punkcie końcowym obsługującym uwierzytelnianie za pomocą klucza API, więc wybierz ten, który najlepiej pasuje do Twojej konfiguracji.

Dostęp do API jest funkcją płatną. Jeśli Twój plan go nie obejmuje, żądania będą odrzucane z błędem 403, nawet jeśli sam klucz jest prawidłowy — zobacz Bramka funkcji płatnych poniżej. Aby wygenerować klucz, zobacz Dostęp do API.

Tylko HTTPS. Wszystkie żądania muszą korzystać z bezpiecznego połączenia. Żądania przesyłane zwykłym protokołem HTTP są odrzucane jeszcze przed uruchomieniem procesu uwierzytelniania.

Cztery metody w skrócie

Metoda Nośnik Kiedy stosować
Parametr zapytania ?apiKey=YOUR_API_KEY Szybkie testy i adresy URL w przeglądarce
Nagłówek X-API-Key: YOUR_API_KEY Integracje produkcyjne
Nagłówek Bearer Authorization: Bearer YOUR_API_KEY Integracje produkcyjne
Token ID Firebase Authorization: Bearer <ID token> Tylko sesje aplikacji własnych

Jeśli obecna jest więcej niż jedna metoda, pierwszeństwo ma parametr zapytania, następnie nagłówek X-API-Key, a na końcu token bearer. W praktyce zawsze przesyła się tylko jedną z nich.

1. Parametr zapytania — ?apiKey=

Dodaj swój klucz na końcu adresu internetowego. Jest to najprostsza forma, która zawsze działa, co czyni ją idealną do szybkich testów, skryptów i wszelkich starszych narzędzi.

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

Uwaga: Adresy internetowe trafiają do historii przeglądarki, logów dostępu serwera i logów proxy. W przypadku wszystkiego, co wykracza poza szybki test, wybierz jedną z poniższych metod nagłówkowych, aby Twój klucz nie był zapisywany na dysku w postaci jawnej.

2. Nagłówek X-API-Key

Prześlij klucz w dedykowanym nagłówku. Dzięki temu nie pojawia się on w adresie URL i jest to zalecany wybór w środowisku produkcyjnym.

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

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

3. Nagłówek Authorization: Bearer

Klucz możesz również przekazać jako standardowy token bearer. Jest to przydatne, gdy Twój klient HTTP lub framework ma już wbudowaną obsługę nagłówków Authorization.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

API automatycznie odróżnia Twój klucz API od tokena logowania, więc ta metoda działa dokładnie tak samo jak X-API-Key.

4. Token identyfikatora Firebase (tylko dla aplikacji własnych)

Jeśli tworzysz własną aplikację, w której użytkownicy logują się za pomocą własnego systemu logowania Your AI Connector, możesz przekazać token identyfikatora Firebase zalogowanego użytkownika jako token bearer zamiast klucza API:

Authorization: Bearer <Firebase ID token>

Token jest weryfikowany przy każdym żądaniu i przypisywany do zalogowanego konta. Ta metoda jest przeznaczona wyłącznie dla sesji aplikacji własnych — nie można wygenerować tych tokenów z poziomu zewnętrznej integracji i nie ma możliwości uzyskania ich bez przejścia przez standardowy proces logowania w aplikacji. W przypadku integracji serwer-serwer oraz integracji zewnętrznych należy użyć klucza API (metody 1–3).

Kiedy używać poszczególnych metod

  • Szybkie testy i jednorazowe skrypty → parametr zapytania (?apiKey=). Najszybszy sposób, działa w przeglądarce.
  • Integracje produkcyjne i wywołania serwer-serwer → X-API-Key lub Authorization: Bearer YOUR_API_KEY. Pozwala uniknąć umieszczania klucza w adresach URL i logach.
  • Aplikacje własne z zalogowanym użytkownikiem Your AI Connector → Authorization: Bearer <Firebase ID token>.

Zakresy kluczy

Twoje konto posiada jeden główny klucz API — ten dostępny w sekcji Ustawienia → Integracje → Klucz API. Ma on pełny dostęp do wszystkich funkcji konta.

Możesz również tworzyć dodatkowe klucze o ograniczonym zakresie: nazwane klucze, które mają dostęp tylko do wybranych części API, na przykład klucz tylko do odczytu ograniczony do analityki na potrzeby pulpitu nawigacyjnego z raportami. Klucz o ograniczonym zakresie przesyła się dokładnie tak samo jak klucz główny (dowolną z metod 1–3 powyżej), ale przy każdym żądaniu jest on weryfikowany pod kątem przypisanych mu uprawnień:

  • Poza dozwolonymi obszarami dostęp jest odmawiany. Operacja zapisu przy użyciu klucza tylko do odczytu lub wywołanie sekcji, do której klucz nie ma uprawnień, skutkuje błędem 403 — key_read_only lub key_scope_denied w polu error_code. Weryfikacja jest celowo rygorystyczna: wszystko, co nie znajduje się wyraźnie w dozwolonych obszarach klucza, jest odrzucane, więc jeśli zobaczysz jeden z tych 403, oznacza to, że klucz po prostu nie obejmuje tego punktu końcowego.
  • Posiada własny limit szybkości (rate-limit). Klucz o ograniczonym zakresie jest liczony oddzielnie od klucza głównego, więc intensywnie działający pulpit nawigacyjny korzystający z takiego klucza nie wyczerpie limitu, od którego zależą inne integracje. Ten limit na minutę wybierasz podczas tworzenia klucza.
  • Nie może zarządzać kluczami API. Tylko właściciel konta — zalogowany lub używający klucza głównego — może wyświetlać, tworzyć, edytować, zmieniać lub unieważniać klucze. Klucz o ograniczonym zakresie nigdy nie może wygenerować klucza o szerszych uprawnieniach.

Zobacz Klucze API, aby dowiedzieć się, jak tworzyć, edytować i unieważniać klucze o ograniczonym zakresie.

Blokada płatnych funkcji

Dostęp do API jest funkcją płatną. Jeśli Twój plan go nie obejmuje, żądanie z poprawnym kluczem zostanie odrzucone z błędem 403:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

Bezpieczeństwo klucza

  • Traktuj klucz jak hasło. Twój główny klucz zapewnia pełny dostęp do konta. Jeśli musisz przekazać klucz narzędziu lub osobie, która potrzebuje tylko częściowego dostępu, utwórz zamiast tego klucz o ograniczonym zakresie — zobacz Zakresy kluczy.
  • Przechowuj go po stronie serwera. Nigdy nie umieszczaj go w kodzie JavaScript przeglądarki, pakiecie aplikacji mobilnej ani w żadnym kodzie, który użytkownik końcowy może odczytać.
  • Przechowuj go w menedżerze sekretów lub konfiguracji po stronie serwera, a nie w systemie kontroli wersji.
  • Zmień go, jeśli wycieknie. Wygeneruj nowy klucz z poziomu pulpitu nawigacyjnego lub wywołaj POST https://api.youraiconnector.com/v1/api-keys/rotate — to natychmiast unieważni stary klucz. Zobacz Klucze API.
  • Zawsze używaj HTTPS, aby klucz był szyfrowany podczas przesyłania.

Następne kroki