Správa přístupu k API

1. Přehled

Mango API v3 používá pro autentizaci Bearer tokeny — každý API požadavek musí obsahovat platný token v HTTP hlavičce. Tokeny slouží jako alternativa k přihlašování uživatelským jménem a heslem a jsou určeny pro automatizované systémy, integrační nástroje (Make, vlastní skripty) a třetí strany.

Tokeny se spravují v aplikaci Mango Admin na adrese https://admin.mango.cloud.

Aby uživatel mohl Mango API volat, musí mít v Mango přiděleno právo API.ACCESS. Toto právo přiděluje administrátor systému.

2. Typy tokenů

2.1 Login token (osobní token uživatele)

Login token je vázán na konkrétního uživatele systému. Při API volání s login tokenem má systém k dispozici identitu tohoto uživatele a uplatňuje jeho přístupová práva.

Typické použití:

• Osobní integrace a skripty
• Testování API v nástrojích jako Postman nebo Bruno
• Make.com scénáře přihlášené pod konkrétním uživatelem

Kdo může vytvářet: každý přihlášený uživatel Mango Admin si vytváří vlastní tokeny.

2.2 Lokační token

Lokační token je vázán na konkrétní lokaci (CT), nikoli na konkrétního uživatele. Při volání API je nutné dodat ID uživatele, jehož jménem se operace provádí, přes hlavičku X-Login-Id.

Typické použití:

• Systémové integrace a daemon procesy bez vazby na konkrétního zaměstnance
• Provozní integrace (billing systémy, provisioning)

Kdo může vytvářet: pouze Super Admin.

3. Vytvoření tokenu

3.1 Vytvoření login tokenu

1. Přihlaste se do Mango Admin: https://admin.mango.cloud
2. V levém menu vyberte Tokeny → Moje tokeny.
3. Klikněte na tlačítko Nový token (vpravo nahoře).
4. Vyplňte formulář: Název (povinný) — pojmenujte token podle účelu; Platnost — zaškrtněte „Bez omezení“ nebo zvolte datum vypršení.
5. Klikněte Vytvořit.
6. Zkopírujte zobrazený token — zobrazí se pouze jednou, po zavření dialogu ho nelze znovu zobrazit.
7. Token bezpečně uložte (heslovník, tajný trezor CI/CD systému).

3.2 Vytvoření lokačního tokenu

1. Přihlaste se jako Super Admin do Mango Admin: https://admin.mango.cloud
2. V levém menu vyberte Tokeny → Lokační tokeny.
3. Klikněte na Nový token.
4. Vyplňte: Název (povinný), Lokace (povinná) — vyberte lokaci, pro kterou token platí, Platnost.
5. Klikněte Vytvořit a zkopírujte token.

4. Použití tokenu v API volání

4.1 Povinné HTTP hlavičky

Login token:

Authorization: Bearer <váš_token>

X-CT: <číslo_lokace>

Lokační token:

Authorization: Bearer <váš_token>

X-Login-Id: <ID_uživatele>

Parametr X-CT určuje lokaci (CT), ve které se operace provádí. U lokačního tokenu je lokace určena tokenem samotným — X-CT se neuvádí.

4.2 Prostředí API

Prostředí	Base URL
Produkce	https://api.mango.cloud/api/v3
Test	https://apiv3-test.devel.ogsoftdev.com/api/v3

Kompletní referenci všech endpointů najdete ve Swagger dokumentaci: https://api.mango.cloud/docs/

5. Zobrazení a správa tokenů

V přehledu tokenů (Mango Admin → Tokeny) jsou vidět: název tokenu, platnost (datum nebo „Bez omezení“), poslední použití (datum nebo „Nikdy“).

Hodnotu tokenu nelze zpětně zobrazit — při ztrátě tokenu vytvořte nový a původní zrušte.

6. Zrušení tokenu

1. V přehledu tokenů klikněte na Zrušit u příslušného tokenu.
2. Potvrďte v dialogu.
3. Token je okamžitě neplatný — veškerá volání s tímto tokenem začnou vracet chybu 401.

Tokeny rušte ihned, pokud: podezříváte na jejich kompromitaci; zaměstnanec, kterému patřily, opustil organizaci; integrace byla ukončena.

7. Bezpečnostní doporučení

• Token nikdy nezapisujte přímo do zdrojového kódu — používejte proměnné prostředí nebo trezor (vault).
• Každé integraci vytvořte vlastní token — usnadní to revokaci bez ovlivnění ostatních systémů.
• Nastavte expiraci u tokenů, kde to dává smysl (např. dočasné skripty).
• Pravidelně kontrolujte seznam tokenů a rušte nepoužívané.

8. Chybové stavy

Kód	Význam
401 Unauthorized	Token je neplatný, vypršel nebo chybí hlavička Authorization
403 Forbidden	Token je platný, ale uživatel nemá právo na danou operaci

9. Podpora

• E-mail: [email protected]
• Hotline: +420 468 000 111 (8:00–16:00)