Skip to main content
SmsManager používá autentizaci API klíčem pro všechny požadavky. Každé volání JSON API v2 a REST API musí obsahovat platný API klíč — nejsou žádné OAuth toky ani session tokeny ke správě. Klíč můžete předat jako HTTP hlavičku (doporučeno pro všechny endpointy) nebo jako query parametr u jednoduchého GET endpointu.

​
Získání API klíče

Přihlaste se ke svému účtu SmsManager a přejděte na stránku Vývojáři. Váš hlavní API klíč je tam zobrazen. Zkopírujte jej a uložte na bezpečné místo — použijete jej v každém požadavku na API.
Prostřednictvím REST API si můžete vytvořit další sub-klíče s izolovaným nebo sdíleným kreditem. Viz Správa API klíčů níže pro podrobnosti.

​
Předávání API klíče

​
Pomocí hlavičky (doporučeno)

Zahrňte svůj API klíč do hlavičky požadavku x-api-key. Tato metoda je podporována na všech endpointech JSON API v2 i REST API.
Příklad cURL:

​
Pomocí query parametru (pouze simple endpoint)

Na endpointu GET /simple/message se můžete autentizovat připojením klíče jako query parametru apikey místo použití hlavičky.
Query parametr apikey je podporován pouze na endpointu GET /simple/message. Všechny ostatní endpointy vyžadují hlavičku x-api-key.

​
Správa API klíčů

Sub-klíče můžete programově vytvářet a spravovat přes REST API. Sub-klíče jsou užitečné, pokud provozujete více integrací nebo služeb a chcete sledovat využití nebo nezávisle odvolávat přístup. Při vytváření sub-klíče můžete nastavit:
  • note — čitelný popisek, abyste snadno identifikovali, která integrace používá který klíč
  • default_callback_url — záložní webhook URL použitá pro všechny zprávy odeslané tímto klíčem, pokud není zadán per-request callback
  • shared — nastavte na true pro sdílení kreditu s nadřazeným účtem nebo na false pro samostatný kredit sub-klíče
  • currency — fakturační měna sub-klíče (EUR nebo CZK; musí odpovídat nadřazenému, pokud shared je true)
API klíče jsou vázány na účet. Sub-klíče vytvořené pod vaším účtem mohou sdílet kredit s vaším hlavním účtem nebo mít svůj vlastní podle toho, jak nastavíte příznak shared při volání REST API.
Sub-klíč pro novou integraci vám vytvoří i AI asistent připojený přes MCP server (nástroj create_child_apikey) — bez toho, aby kdy viděl hlavní klíč workspace. Kód generovaný pomocí AI skills načítá klíč z proměnné prostředí SMSMANAGER_API_KEY, v souladu s doporučeními níže.

​
Úprava klíče a podřízených klíčů

Nastavení klíče měníte přes POST /apikey/update. Všechna pole jsou volitelná a změní se jen ta, která v požadavku pošlete. Hodnota null (nebo prázdný řetězec) nastavení smaže. Požadavek bez jakéhokoli rozpoznaného nastavení vrátí 400. Pokud se nastavení uloží, ale něco vyžaduje vaši pozornost, odpověď obsahuje pole warning. Může jít například o nedostupnou callback URL nebo o nezaregistrovaného výchozího odesílatele. Nadřazený (top-level) klíč upravuje své podřízené klíče stejným endpointem. Do pole apikey uveďte podřízený klíč, který chcete upravit. Musí patřit volajícímu klíči (viz GET /apikey/list). S polem apikey můžete měnit:
  • scope — rozsah oprávnění podřízeného klíče (full, rest-api nebo api),
  • disable — 1 podřízený klíč zablokuje, 0 odblokuje,
  • všechna ostatní nastavení, například note, default_callback_url, default_sender nebo whitelist_ip.
Nastavení se chovají stejně, jako kdyby se podřízený klíč upravoval sám. Například default_sender se ověřuje proti odesílatelům podřízeného klíče. Funguje to i u podřízených klíčů se scope api, které samy /apikey/update volat nemohou.
Zablokovat podřízený klíč
Pole scope a disable jsou přijímána jen společně s apikey. Klíč nikdy nemůže změnit vlastní scope ani vlastní blokaci.
Endpoint POST /apikey/change je zastaralý. Kvůli stávajícím integracím dál funguje, ale v nových integracích použijte POST /apikey/update s polem apikey.

​
IP whitelist

Odesílání zpráv přes API klíč můžete omezit na vybrané IP adresy nebo poskytovatele připojení. Whitelist nastavíte polem whitelist_ip přes POST /apikey/update:
Nastavit IP whitelist
Každá položka se vyhodnocuje podle svého obsahu:
  • Položka obsahující . nebo : se porovnává jako přesná IP adresa. Rozsahy CIDR nejsou podporované.
  • Jakákoli jiná položka se porovnává jako podřetězec názvu ISP nebo organizace, ke které patří IP adresa požadavku.
Whitelist může mít nejvýše 50 položek. Každá položka má nejvýše 100 znaků a nesmí obsahovat čárku (,).
Zprávy odeslané z adresy mimo whitelist se neodešlou. SmsManager je místo odeslání podrží k ručnímu schválení.
Omezení zrušíte hodnotou null nebo prázdným polem []. Aktuální whitelist vrací GET /apikey/me v poli whitelist_ip. Whitelist podřízeného klíče nastavíte stejně, jen do požadavku přidáte pole apikey.

​
Bezpečnostní doporučení

Dodržujte tato doporučení pro ochranu vašich API klíčů a dat uživatelů:
  • Nikdy nezakódujte API klíče do frontendu — klíče v JavaScriptu, mobilních aplikacích nebo veřejných repozitářích mohou být extrahovány a zneužity
  • Používejte proměnné prostředí — načítejte klíče z proměnných prostředí nebo správce tajemství (např. AWS Secrets Manager, HashiCorp Vault), nekomitujte je do přímo do zdrojového kódu
  • Rotujte klíče při kompromitaci — pokud se domníváte, že klíč mohl uniknout, ihned vytvořte nový přes app.smsmanager.com/app/developers nebo REST API, aktualizujte integraci a starý klíč deaktivujte
  • Omezte odesílání na své servery — nastavte IP whitelist, aby klíč odesílal jen z adres, které znáte
  • Používejte sub-klíče pro každou integraci — přiřaďte vyhrazený sub-klíč každé službě nebo prostředí (produkce, staging atd.), abyste mohli odvolat jediný klíč, aniž byste narušili vše ostatní

​
Chyby autentizace

Pokud váš API klíč chybí, je poškozený nebo není autorizován pro požadovanou operaci, API vrátí HTTP odpověď 403.
SmsManager vrací 400 (nikoli 401) pro chyby autentizace. Ujistěte se, že vaše logika zpracování chyb kontroluje odpovědi 400 a zkoumá pole Message v těle odpovědi, aby rozlišila chyby autentizace od validačních chyb.