Uwierzytelnianie

Każde żądanie do Sursa API zawiera w nagłówku Authorization klucz API albo token dostępu OAuth aplikacji:

Authorization: Bearer kb_3f9c…

Klucz identyfikuje organizację i decyduje, co żądanie może widzieć i zmieniać: decydują o tym jego rola, zakresy, profil dostępu i kolekcje. Pod adresem API nie ma sesji ani plików cookie. Każde żądanie jest uwierzytelniane osobno, więc możesz wysyłać żądania równolegle i z kilku serwerów z tym samym kluczem.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Wcześniejsze integracje mogą zamiast tego wysyłać klucz w nagłówku X-API-Key. Jest on nadal akceptowany, ale nowy kod powinien używać Authorization: Bearer.

Rodzaje danych uwierzytelniających

Dane uwierzytelniające	Wygląd	Gdzie działają
Klucz API organizacji	`kb_…`	Każda operacja API, w ramach roli, zakresów, profilu dostępu i kolekcji klucza.
Klucz własnego źródła	`kbsrc_…`	Tylko operacje push jego własnego źródła (`/v1/push/sources/{source_id}/…`).
Token dostępu OAuth	`kbat_…`	Operacje z dokumentacji API, w ramach zakresów tokenu. Token z `POST /oauth/token` uzyskany za pomocą kodu autoryzacji działa w imieniu pracownika, który wyraził zgodę; token `client_credentials` działa w imieniu organizacji, tak jak klucz API. Jest ważny przez 1 godzinę.

Wszystkie wysyła się w ten sam sposób. Klucz własnego źródła nie może niczego odczytywać, wyszukiwać ani zmieniać poza swoim źródłem; używaj go tam, gdzie klucz przechowuje strona trzecia, np. platforma integracyjna.

Błędy uwierzytelniania

Status i kod	Co oznacza	Co zrobić
`401` `auth.not_authenticated`	Brak klucza, błędnie wpisany klucz lub klucz unieważniony.	Sprawdź nagłówek i wartość klucza.
`401` `api_keys.expired`	Minęła data wygaśnięcia klucza.	Utwórz nowy klucz i zastąp nim stary.
`401` `sources.push_key_invalid`	Klucz własnego źródła jest błędny, unieważniony lub należy do innego źródła.	Sprawdź klucz i ID źródła w ścieżce.
`401` `oauth.token_expired`	Token dostępu OAuth wygasł.	Uzyskaj nowy za pomocą tokenu odświeżania.
`403` `api_keys.scope`	Klucz nie ma zakresu potrzebnego do tej operacji.	Dodaj zakres lub użyj klucza, który go ma.
`403` `api_keys.feature_disabled`	Plan organizacji nie obejmuje kluczy API.	Skontaktuj się z administratorem organizacji.
`403` `api_keys.ip_not_allowed`	Żądanie pochodzi z adresu spoza dozwolonych adresów klucza.	Wywołuj API z dozwolonej sieci albo zmień adresy klucza.
`403` `api_keys.mcp_only`	Osobisty klucz MCP został użyty poza operacją `/mcp`.	Do API używaj klucza API organizacji.
`403` `oauth.operation_not_allowed`	Operacja nie należy do publicznego API, więc token OAuth nie może jej wywołać.	Użyj operacji z dokumentacji API.
`403` `org.suspended`	Organizacja jest zawieszona. Jej dane są zachowane.	Skontaktuj się z administratorem organizacji.

403 oznacza, że żądanie zostało uwierzytelnione, ale nie jest dozwolone. Na żądanie dotyczące obiektu, którego klucz nie może widzieć, API odpowiada 404, tak samo jak w przypadku obiektu, który nie istnieje, więc klucz nie może się dowiedzieć, co leży poza jego dostępem.

Działanie jako profil dostępu

Klucz z rolą admin może sprawdzić, co zobaczyłaby inna grupa osób: nagłówek X-View-As wykonuje żądanie jako wybrany profil dostępu i opcjonalnie jako wybrana rola.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Żądania w tym trybie tylko odczytują dane: każda zmiana zwraca 403 z kodem view_as.read_only. Token OAuth ani klucz bez roli admin nie mogą używać X-View-As: API odpowiada wtedy 403 z kodem view_as.admin_key_required. Na nagłówek, który nie wskazuje żadnego istniejącego profilu, API odpowiada 400 z kodem view_as.invalid_header.

Aplikacje przeglądarkowe

API zezwala na żądania z dowolnego pochodzenia (origin) w sieci (Access-Control-Allow-Origin: *) i nigdy nie używa plików cookie, więc strona internetowa może je wywoływać za pomocą fetch. Klucz znajduje się wtedy w kodzie strony i jest widoczny dla każdego, kto z niej korzysta. Wywołuj API z przeglądarki tylko z kluczem, który możesz pokazać tym użytkownikom, np. kluczem viewer ograniczonym do publicznych kolekcji, albo umieść własny serwer między przeglądarką a Sursą.

Co może zrobić tylko pracownik

Klucz API organizacji działa w imieniu organizacji, a nie osoby. Dwie części API należą do ludzi, dlatego działają tylko z tokenem, który działa w imieniu pracownika: z sesją w Sursie albo z tokenem dostępu OAuth wydanym za zgodą pracownika.

Rozmowy należą do osoby. Klucz API organizacji widzi w GET /v1/conversations tylko rozmowy, które sam rozpoczął. Publiczne API nie ma operacji, która rozpoczyna rozmowę, więc dla klucza lista jest zwykle pusta, a rozmowy pracowników nigdy nie są mu pokazywane. Pytania bez rozmowy, przez POST /v1/ask lub POST /v1/chat, działają z każdym kluczem, który ma zakres ask. Aby pobrać listę rozmów pracownika i odczytać historię jednej z nich za pomocą GET /v1/conversations/{conv_id}, wywołaj API z tokenem OAuth w imieniu tego pracownika. Token widzi tylko własne rozmowy tego pracownika; na każdą inną rozmowę API odpowiada 404 z kodem conversations.not_found.

Kartę weryfikuje tylko pracownik. Weryfikacja potwierdza, że osoba sprawdziła treść, dlatego POST /v1/cards/{card_id}/verification/verify i POST /v1/cards/{card_id}/verify wymagają sesji albo tokenu OAuth w imieniu pracownika, który może zweryfikować kartę. Z kluczem API organizacji albo tokenem client_credentials odpowiadają 400 z kodem cards.verify_user_account_required. Najpierw wykonywane są zwykłe sprawdzenia: na kartę, której klucz nie może widzieć, API odpowiada 404, a na żądanie klucza, który nie może jej zweryfikować, 403.