API tokeny

API tokeny

API tokeny vytvárate na stránke API tokeny v paneli (https://panel.cloudweb.sk/api-tokens). Token je hneď po vytvorení zobrazený v plnom tvare presne raz – pri opätovnom otvorení stránky ho už nezobrazíme, treba si ho uložiť na mieste, ktoré vy sami kontrolujete.

Oprávnenia (scopes)

Pri vytváraní tokenu vyberáte jedno alebo viac z týchto oprávnení:

• hostings:read – zobrazenie hostingov
• domains:read – zobrazenie domén
• invoices:read – zobrazenie faktúr
• dns:read – zobrazenie DNS záznamov
• dns:write – vytváranie a úprava DNS záznamov
• dns:delete – mazanie DNS záznamov
• dns:acme – iba pridanie/odobratie _acme-challenge TXT záznamu (certifikáty cez DNS-01)

Oprávnenie dns:write nezahŕňa dns:acme a naopak – ide o samostatné, úzko vymedzené práva. Token, ktorý má bežať na cudzom serveri (napr. na vydávanie certifikátov), by teda mal dostať iba dns:acme, aby jeho prípadný únik neumožnil útočníkovi prepísať bežné A/MX záznamy.

Token je možné obmedziť aj na konkrétne domény zo zoznamu tých, ktoré máte v správe DNS – obmedzenie platí pre REST správu DNS aj pre ACME endpoint. Prehľad jednotlivých typov DNS záznamov, ktoré takto môžete spravovať, nájdete v článku DNS záznamy: čo sú a ako fungujú.

Platnosť, limity

Pri vytváraní zvolíte platnosť v dňoch (1 až 365), alebo token necháte bez expirácie. Na účet môžete mať naraz maximálne 10 tokenov – ak limit dosiahnete, treba najprv niektorý zmazať. Jednotlivý token má obmedzenie 60 požiadaviek za minútu.

Návod v paneli

Stránka API tokenov obsahuje aj návod na použitie priamo v paneli – základnú URL adresu API, formát hlavičky Authorization a zoznam dostupných endpointov podľa vybraných oprávnení. Tento návod je súčasťou prihláseného panela, nie je verejne dostupný bez prihlásenia.

DNS-01 výzva pre wildcard certifikáty

Ak potrebujete vydať wildcard certifikát (*.example.sk) mimo Cloudweb – napríklad cez Traefik, lego, acme.sh alebo certbot – wildcard sa dá overiť iba cez DNS-01 výzvu, teda zápisom _acme-challenge TXT záznamu. Na to slúžia dva verejné endpointy:

• POST https://cloudweb.sk/api/v1/acme/present
• POST https://cloudweb.sk/api/v1/acme/cleanup

Overenie prebieha buď hlavičkou Authorization: Bearer <token>, alebo HTTP Basic autentifikáciou, kde heslom je token (meno sa ignoruje) – vhodné pre nástroje, ktoré vedia iba Basic autentifikáciu. Vyžaduje sa oprávnenie dns:acme. Kontrakt zodpovedá lego providerovi httpreq aj acme.sh providerovi dns_acmeproxy, takže netreba žiadny špeciálny plugin – stačí nastaviť endpoint a token ako meno/heslo.