Role i uprawnienia kluczy API

Każdy klucz API Elido ma przypisaną rolę. Rola określa, co klucz może robić. Wybieranie najmniej uprzywilejowanej roli dla każdego przypadku użycia ogranicza zasięg potencjalnych szkód w razie wycieku klucza.

Trzy role#

Rola	Co może robić
viewer	Odczytuje linki, dane analityczne i ustawienia workspace. Nie może tworzyć, aktualizować ani usuwać czegokolwiek.
editor	Wszystko co viewer, plus tworzenie/aktualizowanie/usuwanie linków, zarządzanie webhookami i uruchamianie importów masowych.
admin	Wszystko co editor, plus zarządzanie członkami workspace, rozliczeniami, kluczami API i regułami IP.

Rolę ustawiasz podczas tworzenia klucza w Ustawienia → Klucze API. Nie można zmienić roli klucza po jego utworzeniu — wydaj nowy klucz z właściwą rolą i unieważnij stary.

Którą rolę wybrać#

Panele analityczne i integracje tylko do odczytu — użyj viewer. Zewnętrzne narzędzie BI, strona statusu pobierająca liczby kliknięć lub wewnętrzny skrypt raportujący potrzebuje tylko odczytu danych.

Potoki CI/CD skracające linki — użyj editor. Skrypt wdrożeniowy tworzący linki do kampanii, integracja CMS generująca krótkie URL-e i większość automatyzacji Zapier/Make należy do tej kategorii.

Automatyzacja administracyjna — użyj admin tylko gdy integracja naprawdę potrzebuje zarządzać członkami lub rozliczeniami. To rzadki przypadek. Większość integracji, które "czuć adminem", to w istocie tylko edytory.

Serwer MCP / agent AI — editor to właściwe ustawienie domyślne, chyba że agent musi zapraszać członków. Pakiet @elido/mcp-server respektuje rolę klucza.

Mapowanie roli na endpointy#

Szybka ściągawka dla typowych wywołań API:

GET    /v1/links              → viewer
POST   /v1/links              → editor
PUT    /v1/links/:id          → editor
DELETE /v1/links/:id          → editor
GET    /v1/analytics/clicks   → viewer
GET    /v1/workspace          → viewer
POST   /v1/workspace/members  → admin
POST   /v1/api-keys           → admin

Pełna dokumentacja jest dostępna pod adresem /api.

Błędy niezgodności zakresu#

Gdy klucz nie ma uprawnień do endpointu, API zwraca:

{
  "error": "forbidden",
  "message": "this key requires the admin role to manage workspace members",
  "required_role": "admin",
  "key_role": "editor"
}

Pole required_role dokładnie mówi, czego potrzebujesz. Rozwiązaniem jest wydanie nowego klucza z wyższą rolą (jeśli jest to zamierzone) lub ponowne rozważenie, czy integracja w ogóle powinna wykonywać tę operację.

Typowe błędy:

• Używanie klucza viewer do tworzenia linków. Rozwiązanie: wydaj klucz editor.
• Używanie klucza editor do zapraszania członka zespołu ze skryptu. Rozwiązanie: wydaj klucz admin lub użyj dashboardu.
• Mylenie roli członkostwa w workspace (Owner/Member) z rolą klucza API. To odrębne pojęcia. Członek zespołu z dostępem "Member" może nadal tworzyć klucz API z rolą admin do własnych integracji — jego uprawnienia w dashboardzie nie są dziedziczone przez klucz.

Rozwiązywanie problemów#

403 na endpoincie, który powinien być dozwolony. Sprawdź rolę klucza w Ustawienia → Klucze API — jest wyświetlana w kolumnie Rola. Jeśli rola wygląda poprawnie, upewnij się, że wysyłasz nagłówek Authorization: Bearer <token>, a nie nagłówek Basic auth ani parametr zapytania.

401 Unauthorized. Klucz jest albo unieważniony, albo token jest nieprawidłowy. Sprawdź kolumnę Status pod kątem odznaki revoked. Jeśli klucz jest aktywny, zweryfikuj, czy skopiowałeś pełny token w momencie jego tworzenia.

Klucz działa przy odczycie, ale nie przy zapisie. Twój klucz ma prawdopodobnie rolę viewer. Wydaj nowy klucz editor.

Potrzebuję różnych uprawnień dla każdej integracji. Wydaj jeden klucz na integrację. Tworzenie i unieważnianie kluczy jest bezpłatne i proste, więc nie ma powodu, by współdzielić klucz między dwoma systemami.