Headless režim a API tokeny
V headless režimu zůstává Laravix vaším redakčním zázemím — obsah, média, uživatelé, nastavení — zatímco obsah konzumuje libovolný frontend (Nuxt, Next.js, mobilní aplikace) přes REST API. Tento článek nastaví headless web od přepnutí režimu po první autentizovaný požadavek.
Šablona vs. headless — per web
Režim je vlastnost každého webu, takže jedna instalace může vedle sebe obsluhovat marketingový web vykreslovaný Blade šablonou i headless aplikaci. Důsledky headless režimu:
- Blade frontend je vypnutý — požadavky na doménu webu vracejí 404.
- V Nastavení se objeví záložka API (místo Vzhledu); ve formuláři obsahu se skryje záložka vizuálního builderu a SEO pole registrovaná v kódu.
- Obsah, média, taxonomie, navigace a nastavení jsou dostupné pod
/api/v1.
1. Přepnutí webu na headless
Při zakládání webu zvolte Režim: Headless (API). U existujícího webu změní režim super admin ve Weby → úprava webu.
2. Vytvoření API tokenu
- V administraci otevřete Nastavení → API.
- Zkopírujte zobrazenou Základní URL API —
https://{vase-domena}/api/v1. - Klikněte na Vytvořit token, pojmenujte ho (např. „produkční frontend") a volitelně nastavte expiraci.
- Token zkopírujte z potvrzovacího dialogu. Zobrazí se jen jednou — databáze ukládá pouze hash.
Tokeny vypadají jako lvx_ následované 40 náhodnými znaky. Seznam tokenů ukazuje prefix, čas posledního použití a expiraci; Odvolat token ho okamžitě smaže.
Tip: Vytvořte jeden token na konzumenta (webový frontend, mobilní aplikace, CI) — půjdou odvolávat nezávisle a uvidíte využití po tokenech.
3. První požadavek
Každý požadavek potřebuje token v hlavičce Authorization:
curl https://example.com/api/v1/pages \
-H "Authorization: Bearer lvx_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Laravix hledá web podle hostname požadavku. Když vaše API volání nejdou přes vlastní doménu webu — lokální vývoj, sdílený API host — pošlete doménu webu explicitně:
curl https://cms.internal/api/v1/pages \
-H "Authorization: Bearer lvx_..." \
-H "X-Site-Domain: example.com"
Chybové odpovědi
| Status | Význam |
|---|---|
401 |
Chybějící, neplatný nebo expirovaný token ({"message": "Missing API token."} apod.) |
403 |
Nalezený web není v headless režimu |
404 |
Hostname / X-Site-Domain neodpovídá žádnému webu, nebo obsah neexistuje |
422 |
Selhala validace (např. /search bez q) |
429 |
Překročen rate limit |
Rate limiting
Požadavky jsou omezené na 120 za minutu na token (bez autentizace per IP). Sledujte standardní hlavičky X-RateLimit-* a na 429 zpomalte.
Jazyky
Obsahové endpointy standardně vracejí výchozí jazyk webu. Jiný zapnutý jazyk si vyžádáte query parametrem locale: /api/v1/pages?locale=en. Neznámé jazyky tiše spadnou na výchozí.
Související články
- API reference — všechny endpointy a tvary odpovědí
- Architektura a multi-tenancy