Klíče API

Zvolte osobní nebo servisní oprávnění, uložte tajnou hodnotu hned při vytvoření a vyměňujte přihlašovací údaje bez ztráty přehledu o tom, kteří klienti je používají.

Klíč API umožňuje volajícímu klientovi jednat s vymezenými oprávněními. Osobní klíč se řídí členstvím a oprávněními konkrétní osoby. Servisní klíč organizace patří organizaci, takže automatizace nemusí záviset na tom, zda některý z kolegů odejde. S RBAC může mít servisní klíč také vlastní roli a rozsah přístupu k prostředkům.

Tajná hodnota klíče se zobrazí při jeho vytvoření a později ji ze záznamů o klíči nelze znovu získat. Ihned ji uložte do správce tajných údajů nebo do úložiště přihlašovacích údajů, které volající klient podporuje. Neukládejte ji do zdrojových souborů ani konfigurace uložené v repozitáři a nesdílejte ji na snímcích obrazovky ani ve zprávách podpoře.

Pro práci pod vlastní identitou používejte osobní klíč #

Ve vybrané organizaci přejděte do Nastavení → Klíče API → Osobní, vytvořte osobní klíč a pojmenujte ho. Člen organizace si ho může vytvořit pro vlastní potřebu. Oprávnění klíče se řídí aktuálním členstvím a skutečně platnými oprávněními jeho tvůrce. Na rozdíl od servisního klíče mu nelze přiřadit samostatnou roli ani rozsah přístupu pro jednotlivé lokalizační engine.

Osobní klíč se hodí pro lokálního klienta, který jedná jménem osoby, jež ho obsluhuje. Pokud tato osoba organizaci opustí nebo přijde o oprávnění, změní se i přístup klíče. Pokud automatizace organizace nemá záviset na tom, zda má daná osoba nadále přístup, použijte servisní klíč.

Vytvořte servisní klíč #

Ve vybrané organizaci přejděte do Nastavení → Klíče API → Organizace a vyberte Nový klíč organizace. Servisní klíče jsou dostupné ve všech plánech. K vytvoření je potřeba org:manage_api_keys.

Bez RBAC nelze oprávnění servisního klíče omezit: umožňuje číst a překládat pomocí všech lokalizačních engine v organizaci. Ve formuláři pro vytvoření se místo polí pro roli a engine zobrazí poznámka.

Tento základní přístup klíči neumožňuje upravovat ani odstraňovat lokalizační engine, provádět kontrolu překladů ani spravovat organizaci.

S RBAC můžete klíči přiřadit roli, rozsah přístupu k lokalizačním engine nebo obojí a později tato nastavení upravit. Volající klient musí mít oprávnění delegovat vybranou roli a překládat pomocí každého lokalizačního engine v daném rozsahu. Samotné oprávnění ke čtení nestačí k udělení přístupu pro překlad.

Povolené servisní role jsou engine:read a engine:translate. Role musí patřit organizaci a nesmí obsahovat širší oprávnění ke správě. Servisní klíč může být i bez role a využívat pouze záměrně udělená oprávnění k prostředkům.

Rozsah přístupu k lokalizačním engine a k obsahovým prostředkům nastavte samostatně a poté znovu načtěte hodnotu každého uloženého pole. Jedna aktualizace oprávnění může selhat, zatímco jiná uspěje. Oprávnění vyplývající z role a výslovně udělená oprávnění se sčítají; užší rozsah neruší širší přístup vyplývající z role. S RBAC samotné vytvoření klíče neposkytuje využitelná oprávnění k překladu, pokud klíč nemá odpovídající roli ani udělená oprávnění k prostředkům.

K vytváření klíčů a úpravám rozsahu přístupu používejte rozhraní pro správu klíčů. Při automatizaci tohoto životního cyklu ověřte, že zvolený klient zpřístupňuje požadovanou operaci správy. Nepředpokládejte, že ji podporují všichni klienti.

Před odebráním RBAC

Po odebrání RBAC získají běžné servisní klíče znovu přístup ke čtení a překládání v celé organizaci. Uložená omezení rolí a engine už tento přístup neomezují. Pokud tato omezení potřebujete zachovat, před odebráním RBAC klíče odvolejte nebo vyměňte. Přihlašovací údaje určené ke konkrétním účelům, například klíče SCIM, mají samostatné požadavky na přístup.

Vyměňte nebo odvolejte přihlašovací údaj #

Rotace spočívá v ruční výměně:

  1. Vytvořte náhradní klíč požadovaného typu s nejnižšími nezbytnými oprávněními.
  2. Uložte jeho tajnou hodnotu pomocí mechanismu pro správu tajných údajů volajícího klienta.
  3. Aktualizujte klienty, kteří klíč používají, a přes rozhraní, které podporují, ověřte jednoduchou operaci odpovídající zamýšlenému použití.
  4. Po ověření odvolejte starý klíč. Pokud únik vyžaduje okamžité omezení rizika, nejprve klíč odvolejte a počítejte s přerušením provozu.
  5. Zkontrolujte aktuální záznamy o klíčích a selhání volajících klientů, abyste odhalili případné přehlédnuté závislosti.

Člen organizace s přístupem k záznamu o klíči může odvolat běžný osobní nebo servisní klíč. Toto oprávnění k odvolání je širší než oprávnění k vytvoření servisního klíče nebo úpravě jeho rozsahu přístupu. Klíč SCIM může odvolat pouze vlastník organizace. Při komunikaci o odebrání uvádějte identifikátor klíče, nikoli jeho tajnou hodnotu.

Odvolání nevymaže kopie uložené jinde ani nezruší relace v prohlížeči. Tento životní cyklus nepředpokládá žádný plán automatické rotace ani vypršení platnosti.

Nakonfigurujte klienta, který bude klíč používat #

Požadavky REST používají hlavičku X-API-Key vybraného API. Kód 401 signalizuje problém s ověřením totožnosti, kód 403 odmítnutí kvůli oprávněním. V prvním případě zkontrolujte přihlašovací údaj, ve druhém oprávnění dané identity a rozsah přístupu k prostředkům. Nevkládejte přihlašovací údaje do narychlo sestavených URL.

Podrobnosti o tom, jak volající klient přenáší a ukládá údaje, najdete v dokumentaci Ověřování API, Ověřování CLI nebo Specifikace připojení MCP. Vybraný lokalizační engine musí zůstat v rozsahu oprávnění daného volajícího klienta.