Автентифікація API: ключі й токени

Для розробників, у коді: ключ віджета і перевірка Origin у рантаймі; ключ керування, сесія та токен ідентичності в API керування; що повертає кожна невдача.

Рантайм: ключ віджета плюс Origin

Кожен запит до рантайму несе ключ віджета сайту (wk_…), і сервер перевіряє дві речі: що ключ існує, є ключем віджета і активний; і, коли ключ має список дозволених origin, що заголовок Origin запиту є в цьому списку.

Куди йде ключ	Ендпоінти
заголовок `X-Widget-Key`	`POST /message`, `GET /widget/config`, `POST /tts`, `GET /conversation`
у кадрі чи тілі як `widget_key`	`WS /ws` (кожен кадр, що починає хід), `WS /ws/stt` (перший кадр), `POST /followed`, `POST /handoff`, `POST /handoff/opened`

Невдача	HTTP	Сокет	Detail
ключа немає або такого не існує	`401`	кадр `error` `unauthorized`, потім закриття `1008`	`Missing widget key` / `Invalid widget key`
ключ неактивний	`403`	`forbidden`, закриття `1008`	`Widget key is inactive`
Origin не дозволений	`403`	`forbidden`, закриття `1008`	`Origin not allowed`

Ключ без дозволених origin приймає будь-який origin (таким може бути лише старий ключ: панель завжди ставить щонайменше origin самого сайту). Власний origin панелі довірений на рівні платформи, тож її прев’ю працює без внесення в список. CORS відображає будь-який Origin і відповідає на preflight, але перевірка — не CORS, а ключ і список.

Ключ публічний за задумом (він у HTML кожної сторінки), тож межа — список origin. Небраузерний клієнт може підробити Origin; рантайм збудовано з цим на увазі — див. Огляд. Тримайте окремий ключ на кожне середовище і вказуйте лише ті origin, які кожному потрібні.

API керування: три входи

Спосіб	Заголовок	Від чийого імені
Ключ керування	`Authorization: Api-Key <ключ>`	власник, який створив ключ — кожен запит обмежений сайтами цього власника
сесія	власне cookie панелі, з CSRF на записах	власник, що увійшов; те, чим користується панель
токен ідентичності	`Authorization: Bearer <токен>`	користувач, для якого видано токен — його передає власний ко-пілот панелі; не для клієнтів

Ключ керування створюється на екрані API-ключів панелі, показується раз і зберігається як хеш; прочитати його назад неможливо. Замінюйте з того самого екрана. Api-Key порівнюється без урахування регістру, а заголовок має складатися рівно з двох частин.

Кожна невдача автентифікації в API керування відповідає 403 з {"detail": "…"} — Authentication credentials were not provided., Invalid API key., Invalid Api-Key header. — а не 401. Дійсний ключ, що дістався до чужого рядка, отримує 404, ніколи не 403: об’єкти іншого власника для вас не існують.

Два інші 403 схожі, але це не автентифікація: обмеження тарифу (Your plan (Starter) does not include custom tools and events. Upgrade to Growth to add them.) і ліміт тарифу (Source limit reached for your plan (500/500). Upgrade to add more.). Обидва — просто {"detail": "…"}, без поля з кодом.

Обмеження на власника

Усе в API керування фільтрується за власником, до якого розв’язується посвідчення. ?site= звужує список до одного з сайтів власника; коректно сформований чужий id — це 404 на insights, overview, analytics і content-gaps і порожній список на списку ресурсів — ніколи не чужі дані.

Токен ідентичності, для допитливих

Панель видає 15-хвилинний HMAC-токен власнику, що увійшов (GET /api/widget-identity/, лише з сесії), передає його в Shukai.setUser, а інструменти ко-пілота надсилають його назад як Bearer {{user}} — із тим самим обмеженням на власника, що й панель. Ваш додаток робить те саме зі своїми токенами, які перевіряє ваш власний API; формат токена панелі — не те, чим ви користуєтеся. Ідентичність користувача.