API klíč je heslo, které nepoužívá člověk, ale program. Když má nějaký jiný systém, třeba váš firemní web, e-shop nebo aplikace od dodavatele, sám číst fotky z archivu nebo do něj fotky ukládat, musí se PhotoPicku prokázat. Přihlašovací údaje konkrétního člověka se k tomu nehodí: patří jednomu člověku a napojení přestane fungovat ve chvíli, kdy si změní heslo nebo z firmy odejde. API klíč je proto samostatné pověření vydané pro jeden systém, se svým seznamem povolených činností a s možností kdykoli ho zrušit, aniž byste komukoli sahali na heslo.
Tento článek popisuje, co uděláte vy jako správce účtu. Co s klíčem dál dělá vývojář, je popsané v technické dokumentaci na adrese developer.photopick.net. Nemusíte jí rozumět, předejte ji tomu, kdo napojení připravuje.
Než začnete
- Potřebujete oprávnění API klíče. Je to jedna z položek, které se zaškrtávají u skupiny oprávnění. Z přednastavených skupin ji má jen skupina Administrátor. Bez tohoto oprávnění se položka API klíče v nastavení vůbec nezobrazí, takže neuvidíte chybovou hlášku, ale prázdné místo. Podrobně to popisuje článek Co která skupina smí.
- Funkce patří do tarifu Professionals. V nižších tarifech sekci otevřete, ale místo tabulky v ní najdete hlášku „API klíče jsou v tarifu Professionals" a dvě tlačítka, Zobrazit předplatné a Co API umí. Co který tarif obsahuje a jak se cena odvíjí od tarifu a kapacity, najdete v ceníku www.photopick.cz/pricing.
- Vyžádejte si od vývojáře dvě věci předem: seznam IP adres, ze kterých se jeho systém bude hlásit (IP adresa je číselná adresa počítače nebo serveru v síti), a výčet činností, které má klíč umět, tedy jestli má fotky jen číst, nebo je i nahrávat a mazat.
Kdo má klíč v ruce, dostane se k datům v archivu bez přihlašování a bez hesla. Zacházejte s ním jako s heslem k účtu, ne jako s adresou nebo číslem objednávky.
Postup
- Otevřete Nastavení → API klíče. Položka je v postranním seznamu nastavení ve skupině Lidé a přístup.
- Klikněte vpravo nahoře na tlačítko Vytvořit klíč. Otevře se okno Vytvořit API klíč.
- Vyplňte pole Název klíče. Název není tajný a na funkci klíče nemá vliv, slouží vám k tomu, abyste v tabulce poznali, komu klíč patří. Napište tedy třeba „Firemní web" nebo jméno dodavatele. Vejde se do něj nejvýše 40 znaků a prázdný zůstat nesmí.
- Do pole IP whitelist vypište adresy serverů, ze kterých se smí klíč používat, každou na samostatný řádek. Adresy vám dodá vývojář, vy je opíšete přesně tak, jak je dostanete. Když pole necháte prázdné, klíč funguje odkudkoli z internetu.
- Do pole Platnost do vyberte datum, kterým klíč skončí. Klíč platí i v tento den, den poté už ne. Prázdné pole znamená, že klíč platí, dokud ho nesmažete; napovídá to i text u pole „Prázdné = bez expirace".
- V části Oprávnění zaškrtejte pouze činnosti, které napojení opravdu potřebuje. Na výběr jsou Číst údaje zákazníka, Číst fotky, Nahrávat a upravovat fotky, Mazat fotky, Číst tagy a Spravovat tagy; poslední dvě se týkají štítků. Předem jsou zaškrtnuté první dvě, tedy jen čtení. U pole je i doporučení „Doporučujeme jen nezbytné minimum." Aspoň jedna položka musí zůstat zaškrtnutá.
- Potvrďte tlačítkem Vytvořit klíč.
Co se stane potom
Otevře se okno API klíč vytvořen a v něm výrazné upozornění: „Toto je jediná příležitost klíč zobrazit. Uložte ho na bezpečné místo." Není to formalita. PhotoPick si hodnotu klíče neukládá v čitelné podobě, takže po zavření okna už ji nikdo, ani podpora, znovu nezobrazí.
- Klikněte kamkoli do tmavého pole s klíčem. Text se označí a zkopíruje do schránky, ikona vpravo se změní na fajfku a popisek na Zkopírováno.
- Klíč hned vložte tam, kam patří natrvalo: do správce hesel, do firemního trezoru na hesla nebo přímo do nastavení systému, který ho bude používat.
- Teprve potom okno zavřete tlačítkem Zavřít.
V tabulce klíčů pak u každého řádku vidíte:
| Sloupec | Co v něm je |
|---|---|
| Název | název, který jste zadali |
| Oprávnění | činnosti, které klíč smí |
| Vytvořeno | jak dávno klíč vznikl |
| Platnost do | datum konce platnosti, nebo „Bez expirace" |
| IP whitelist | „Bez omezení", nebo počet adres; po najetí myší se adresy vypíšou |
| Akce | tlačítko pro smazání klíče |
Samotná hodnota klíče už v tabulce nikde není a hotový klíč se nedá upravit. Změna názvu, adres, platnosti i oprávnění se řeší tak, že vytvoříte nový klíč a starý smažete.
Když má vaše skupina oprávnění Historie, poznáte v historii souboru i to, že fotku nahrál nebo změnil program: u záznamu je odznak API a vedle něj název klíče. To je další důvod, proč klíče pojmenovávat srozumitelně.
Bezpečné zacházení s klíčem
- Neposílejte klíč e-mailem ani chatem. Zpráva zůstane ve schránce odesílatele i příjemce, přeposílá se dál a přečte ji každý, kdo se do některé z těch schránek dostane. Použijte správce hesel, který umí sdílet položku, nebo klíč do cílového systému zadejte sami.
- Klíč nepatří do zdrojového kódu. Zapsaný přímo v souborech projektu zůstane v úložišti kódu i v jeho historii a vidí ho každý, kdo k projektu má přístup. Řekněte dodavateli, že klíč má být v nastavení prostředí, ne v kódu.
- Vyplňte IP adresy. Omezení na adresy je nejlevnější způsob, jak snížit riziko: i kdyby klíč unikl, z cizího počítače nebude fungovat.
- Dávejte jen nezbytná oprávnění. Systém, který na webu jen zobrazuje fotky, nepotřebuje právo mazat.
- Jeden klíč na jedno napojení. Pak můžete jeden zrušit, aniž byste vypnuli ostatní, a v historii souboru poznáte, který systém co udělal.
- Při jakémkoli podezření klíč smažte a vytvořte nový. Netýká se to jen prokázaného úniku, ale i situace, kdy jste klíč omylem poslali chatem nebo kdy od firmy odchází dodavatel.
Smazání klíče
- V tabulce najděte řádek s klíčem a ve sloupci Akce klikněte na ikonu koše.
- Otevře se dotaz Smazat API klíč? s upozorněním, že klíč se zadaným názvem okamžitě přestane fungovat a že akce je nevratná.
- Potvrďte tlačítkem Smazat.
Smazaný klíč se nedá vrátit ani znovu zobrazit. Systém, který ho používal, ztratí přístup a jeho volání skončí chybou; u napojení, které klíč právě používá, se změna plně projeví během několika minut. Když řešíte podezření na únik, smažte klíč hned a nový vystavte až potom.
Časté potíže
Položku API klíče v nastavení vůbec nevidím
Sekce se zobrazí jen členům, jejichž skupina oprávnění má zaškrtnuté oprávnění API klíče. Z přednastavených skupin ho má jen skupina Administrátor, takže běžný člen týmu položku v nastavení nenajde. Požádejte administrátora účtu, aby vám oprávnění přidal, nebo aby klíč vytvořil za vás.
Druhá možnost: účet má předplatné po splatnosti. Pak zůstane použitelná jen sekce Předplatné a ostatní položky nastavení jsou zašedlé s ikonou zámku a popiskem „Dostupné až po obnovení předplatného."
Sekci otevřu a je v ní jen hláška o tarifu
Hláška „API klíče jsou v tarifu Professionals" znamená, že váš účet má tarif Lite nebo Business. Klíče v nich vytvořit nelze a už vytvořené klíče po přechodu na nižší tarif přestanou fungovat. Tlačítko Zobrazit předplatné vede do sekce Předplatné, tlačítko Co API umí otevře technickou dokumentaci pro vývojáře. Změna tarifu se v aplikaci neprovádí, napište na [email protected].
Klíč jsem si nepoznamenal a okno jsem zavřel
Hodnota klíče se znovu zobrazit nedá, a to ani na žádost podpory; PhotoPick ji v čitelné podobě neuchovává. Klíč v tabulce smažte a vytvořte nový. Nic jiného nepřijdete, klíč se ještě nestihl nikam napojit.
Klíč přestal fungovat
Projděte řádek klíče v tabulce a zkontrolujte v tomto pořadí:
- Sloupec Platnost do. Klíč platí i v uvedený den, ale následující den už ne. Když datum uplynulo, vytvořte klíč nový.
- Jestli klíč v tabulce vůbec je. Smazat ho může kdokoli s oprávněním API klíče, i jiný správce.
- Tarif účtu. API funguje jen v tarifu Professionals; po přechodu na nižší tarif přestanou fungovat všechny klíče najednou.
- Sloupec IP whitelist. Když systém dodavatele změnil server nebo mu poskytovatel změnil adresu, hlásí se z adresy, která v seznamu není.
- Oprávnění klíče. Když napojení selhává jen u některé činnosti, například při nahrávání, chybí klíči příslušné oprávnění. Doplnit ho nelze, vytvořte nový klíč se správným výběrem a starý smažte.
Dodavatel hlásí, že ho aplikace odmítá kvůli IP adrese
Klíč má vyplněný seznam adres a adresa, ze které se systém hlásí, v něm není. Najeďte v tabulce myší na počet adres ve sloupci IP whitelist a porovnejte seznam s tím, co dodavatel uvádí. Nejčastější příčiny: dodavatel poslal adresu své kanceláře, ale program běží na serveru s jinou adresou; adresa se u poskytovatele změnila; do seznamu se zapsal rozsah adres místo konkrétních adres.
Vyžádejte si od dodavatele přesnou adresu, ze které se jeho systém hlásí ven, a vypište každou adresu na samostatný řádek. Seznam u hotového klíče upravit nejde, vytvořte nový klíč a starý smažte.
Nevím, jakou platnost nastavit
Prázdné pole znamená, že klíč platí, dokud ho někdo nesmaže. To se hodí pro trvalá napojení, jako je firemní web. Konkrétní datum je pojistka pro dočasné věci: zkušební provoz, jednorázové přenesení fotek nebo práci externisty na projektu s domluveným koncem.
U trvalého napojení datum spíše nevyplňujte. PhotoPick na blížící se konec platnosti neupozorňuje, takže by vám napojení vypadlo uprostřed provozu bez varování. Bezpečnost řešte omezením adres a oprávnění, ne datem.
Nový klíč nefunguje ani na začátku
Zkontrolujte pole Platnost do. Když se do něj omylem dostalo datum v minulosti, klíč je neplatný od začátku a systém dodavatele ho neuplatní. Vytvořte nový klíč se správným datem, nebo pole nechte prázdné.
Tlačítko Vytvořit klíč hlásí chybu
Okno má tři podmínky, které musí být splněné: pole Název klíče nesmí zůstat prázdné, název smí mít nejvýše 40 znaků a v části Oprávnění musí být zaškrtnutá aspoň jedna položka. Když jste odškrtli i ty dvě přednastavené, klíč nevznikne. Doplňte chybějící údaj a potvrďte znovu.
Kolega odešel z firmy a nevím, které klíče vytvořil
Tabulka ukazuje název, oprávnění, stáří a platnost klíče, ne jméno člověka, který ho založil. Postupujte takto:
- Projděte seznam a označte si klíče, jejichž název neříká, k čemu slouží.
- U každého napojení, o kterém víte, si s jeho správcem nebo dodavatelem potvrďte, který klíč používá.
- Nahlédněte do historie u fotek, které nahrál nebo měnil program. U záznamu s odznakem API je uvedený název klíče, takže poznáte, které klíče jsou opravdu v provozu.
- Klíč, ke kterému se nikdo nehlásí, smažte. Je bezpečnější ho zrušit a v případě potřeby vystavit nový, než ho nechat platit dál.
Záznam o tom, kdo klíč vytvořil, PhotoPick vede, ale v zákaznickém účtu není vidět. Když potřebujete jméno zakladatele klíče znát, napište na [email protected].
Potřebuji klíč vyměnit bez výpadku
Klíčů může v účtu existovat víc naráz, výměnu proto dělejte překrytím a nikdy ne obráceně:
- Vytvořte nový klíč se stejným seznamem adres a stejnými oprávněními jako ten dosavadní. Pojmenujte ho tak, abyste ho od starého rozeznali.
- Předejte ho bezpečnou cestou tomu, kdo napojení spravuje, a nechte ho klíč vyměnit v nastavení jeho systému.
- Nechte si potvrdit, že napojení běží na novém klíči.
- Teprve pak starý klíč v tabulce smažte.
Kdybyste starý klíč smazali dřív, napojení přestane fungovat okamžitě a fotky se na webu nebo v cílovém systému přestanou zobrazovat.
Podezřívám, že se klíč dostal k nepovolané osobě
Tady se pořadí obrací: nejdřív mažte. Smažte klíč v tabulce, teprve potom vytvořte nový a předejte ho dodavateli. Krátký výpadek napojení je menší škoda než přístup cizího člověka k archivu. Když si nejste jistí, který z klíčů unikl, smažte všechny a vystavte je znovu; nová sada klíčů je otázka několika minut.