Aktualizovné: 24. Apríl 2026

Setup API

Úvod do Control Panel API

Control Panel API je REST/OpenAPI rozhranie pre automatizáciu vybraných operácií v systéme Setup.Platon.sk. API je dostupné na adrese https://setup.platon.sk/api/ a používa štandardné HTTP metódy a JSON odpovede.

Rozhranie obsahuje skupiny endpointov ako napríklad DNS, Email, Domain, Vehicle, System, OAuth a ďalšie. Aktuálna OpenAPI špecifikácia je dostupná na adrese https://setup.platon.sk/api/openapi.json.

Autentifikácia Bearer tokenom

Všetky chránené požiadavky do API používajú HTTP hlavičku Authorization s Bearer tokenom:

Authorization: Bearer YOUR_TOKEN

Príklad požiadavky na API endpoint:

curl -H "Authorization: Bearer YOUR_TOKEN" \
	https://setup.platon.sk/api/system/hello

Token získate buď ako API kľúč vytvorený priamo v Control Paneli, alebo cez OAuth autorizáciu používateľa.

Dve možnosti získania tokenu

A) API kľúč

API kľúč si vytvorí používateľ priamo v Control Paneli. Tento prístup je vhodný najmä vtedy, keď integráciu prevádzkuje priamo zákazník alebo jeho interný systém.

API kľúč použite pre:

• backend skripty,
• cron úlohy,
• interné integračné skripty,
• desktop alebo lokálne aplikácie používané priamo zákazníkom.

B) OAuth

OAuth použite vtedy, keď aplikácia potrebuje konať v mene používateľov Platon Technologies a používateľ má prístup potvrdiť po prihlásení svojím CNAME.

OAuth je vhodný pre:

• aplikácie tretích strán,
• SaaS integrácie,
• aplikácie, ktoré konajú v mene viacerých používateľov Platon Technologies,
• riešenia, kde používateľ nemá ručne vkladať API kľúč do cudzej aplikácie.

Ak automatizáciu vlastní a prevádzkuje zákazník, použite API kľúč. Ak aplikácia patrí tretej strane alebo má obsluhovať viacerých zákazníkov, použite OAuth.

OAuth flow

Control Panel API používa OAuth Device Authorization flow. Aplikácia najprv zistí dostupné scopes, potom vytvorí OAuth požiadavku, presmeruje používateľa na potvrdenie prístupu a následne kontroluje stav autorizácie.

Získanie dostupných scopes

Endpoint:

GET https://setup.platon.sk/api/oauth/scopes

Scopes určujú, ku ktorým častiam API bude mať token prístup. Aplikácia má žiadať iba minimálne potrebné oprávnenia.

Vytvorenie OAuth požiadavky

Endpoint:

POST https://setup.platon.sk/api/oauth/requests

Príklad požiadavky:

curl -X POST https://setup.platon.sk/api/oauth/requests \
	-H "Content-Type: application/json" \
	-d '{
		"app_name": "Example Integration",
		"app_url_homepage": "https://example.com",
		"app_url_return": "https://example.com/oauth/return",
		"scopes": ["dns:read"]
	}'

Vzorová odpoveď:

{
	"verify_token": "string",
	"access_token": "string",
	"redirect_url": "string",
	"verify_url": "string",
	"verify_interval_seconds": 0
}

Aplikácia presmeruje používateľa na hodnotu redirect_url. Pri CLI alebo desktop aplikácii sa táto URL zobrazí používateľovi, aby ju otvoril v prehliadači.

Používateľ sa na stránke prihlási svojím CNAME a potvrdí požadovaný prístup. Aplikácia medzitým pravidelne kontroluje stav autorizácie cez hodnotu verify_url.

Polling interval nesmie byť nižší ako hodnota verify_interval_seconds, aby aplikácia zbytočne nezaťažovala API.

Endpoint pre overenie OAuth požiadavky:

GET https://setup.platon.sk/api/oauth/requests/verify?verify_token=VERIFY_TOKEN

Úspešná odpoveď po autorizácii:

{
	"status": "string",
	"token": "string",
	"token_expire": "string",
	"cname": "string",
	"error": "string"
}

Význam polí:

• token je Bearer token pre volania Control Panel API,
• token_expire obsahuje čas expirácie tokenu,
• cname identifikuje autorizovaného zákazníka.

Obnova tokenu

OAuth token je možné pred expiráciou obnoviť cez endpoint:

POST https://setup.platon.sk/api/oauth/tokens/refresh

Požiadavka používa aktuálny Bearer token v hlavičke Authorization. Endpoint vráti nový token a jeho novú expiráciu.

curl -X POST https://setup.platon.sk/api/oauth/tokens/refresh \
	-H "Authorization: Bearer YOUR_TOKEN"

Zneplatnenie tokenu

Token je možné zneplatniť alebo odstrániť cez endpoint:

DELETE https://setup.platon.sk/api/oauth/tokens

Tento endpoint použite pri odhlásení aplikácie, odpojení integrácie alebo pri podozrení, že token už nemá zostať aktívny.

curl -X DELETE https://setup.platon.sk/api/oauth/tokens \
	-H "Authorization: Bearer YOUR_TOKEN"

SDK for Developers

Pre vývojárov sú dostupné SDK klienti generovaní z OpenAPI špecifikácie:

• PHP: https://github.com/platon-net/cp-php-sdk
• Typescript: https://github.com/platon-net/cp-typescript-sdk
• Kotlin: https://github.com/platon-net/cp-kotlin-sdk
• Swift: https://github.com/platon-net/cp-swift-sdk

SDK klienti zjednodušujú volanie endpointov, prácu s modelmi a aktualizáciu klienta podľa aktuálnej OpenAPI špecifikácie.

Praktické poznámky

• Tokeny nikdy neukladajte verejne, neposielajte ich do frontendu a necommitujte ich do repozitára.
• Pri OAuth žiadajte iba minimálne scopes potrebné pre konkrétnu integráciu.
• Pre third-party integrácie preferujte OAuth, aby používateľ prístup vedel bezpečne potvrdiť a neskôr odobrať.
• API kľúče používajte najmä pre server-to-server automatizáciu a interné skripty zákazníka.