Авторизация
Здесь всё, что API проверяет до того, как запрос дойдёт до эндпоинта: токен, права и сайт, а как получить токен в консоли — на странице «Доступ и токен».
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.
Токен
Токен — строка op_ и 64 шестнадцатеричных символа, у пользователя он один. Своих прав у токена нет: он действует от имени владельца на всех сайтах, где тот администратор, поэтому храните его как пароль. Передайте токен заголовком Authorization: Bearer или X-OnPress-Key — оба равноправны. Например, список фреймов сайта:
curl -s "$API/site/$SITE/frames" \
-H "Authorization: Bearer $OP_TOKEN"| Заголовок | Формат | Описание |
|---|---|---|
Authorization | Bearer op_… | основной способ |
X-OnPress-Key | op_… | то же самое без слова Bearer; читается, только если нет Authorization: Bearer |
Сервис запоминает проверенный токен на минуту: новый токен работает сразу, а отозванный или перевыпущенный может проходить ещё до минуты. Время последнего обращения last_used_at обновляется не чаще раза в минуту. Показать, перевыпустить и отозвать токен — эндпоинты /me/api-token в справочнике пользователей.
| Код | Статус | Когда | Что делать |
|---|---|---|---|
missing_token | 401 | нет ни Authorization: Bearer, ни X-OnPress-Key | добавить заголовок с токеном |
invalid_token | 401 | токен не той формы, неизвестен или отозван | взять действующий токен в консоли или через GET /me/api-token |
too_many_auth_failures | 429 | больше 20 неудачных попыток за минуту с одного адреса | подождать Retry-After секунд и исправить токен |
Сессия консоли
Консоль https://onpress.pro/dashboard/ ходит в тот же API не токеном, а сессионной кукой после входа почтой, через Google или Telegram. Эндпоинты принимают и куку, и токен; если в запросе есть и то и другое, а кука истекла, проверяется токен. Запрос с кукой принимается только с адреса консоли, иначе — 403 cross_origin. Агенту и скрипту кука не нужна, вход и продление сессии описаны в разделе «Состояние API».
Права
Роль одна — администратор сайта: ему открыты все эндпоинты сайта, и чтение, и запись. Участник сайта без прав администратора получает 403 insufficient_role на любом эндпоинте сайта, включая чтение. Эндпоинты сети — /me, /sites, /auth, /health, /frames/system — живут без префикса сайта: свой профиль, кредиты, тарифы и библиотека системных фреймов доступны любому владельцу токена, а /sites/{id} отвечает только администратору этого сайта. Например, свой профиль:
curl -s "$API/me" \
-H "Authorization: Bearer $OP_TOKEN"Выбор сайта
Сайт называется в пути: $API/site/{siteId}/…. siteId — девять знаков из цифр 2–9 и латиницы без похожих букв l, o, I, O, например x9HTLHECq; он выдаётся при создании сайта и больше не меняется. Под этим префиксом живут все эндпоинты сайта: /pages, /data, /frames, /menus, /media, /users, /docs/sidebar, /seo, /redirects и остальные из справочника. Например, системные данные сайта:
curl -s "$API/site/$SITE/data/system" \
-H "Authorization: Bearer $OP_TOKEN"Ответ на таком адресе называет сайт полем site_id и заголовком X-OnPress-Site-Id, внутренний номер сайта в нём не появляется. Несуществующий и чужой сайт отвечают одинаково — 404 site_not_found с одним и тем же текстом, поэтому id сайтов нельзя перебрать.
| Параметр | Где | Тип | Описание |
|---|---|---|---|
siteId | путь /site/{siteId}/… | строка | id сайта из девяти знаков |
siteId приходит в ответе POST /sites при создании сайта и полем site_id в GET /sites/{id} и GET /data; в консоли он виден в разделе «Данные». /sites/{id} принимает в пути siteId или домен сайта.
| Код | Статус | Когда | Что делать |
|---|---|---|---|
site_not_found | 404 | сайта с таким siteId нет или вы не его администратор | проверить siteId в GET /data или в консоли |
insufficient_role | 403 | вы участник сайта, но не администратор | попросить администратора сайта выдать права |
cross_origin | 403 | запрос с кукой сессии пришёл не с адреса консоли | отправить запрос с токеном |
Лимиты
Каждый ответ эндпоинта с авторизацией несёт заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset — unix-время, когда освободится самый старый запрос окна. Лимит токена считается на пользователя, а не на токен, и перевыпуск его не обнуляет; у каждой сессии консоли своё окно, отдельное от токена. Например, посмотреть остаток лимита:
curl -s -D - -o /dev/null "$API/site/$SITE/menus" \
-H "Authorization: Bearer $OP_TOKEN"x-onpress-site-id: x9HTLHECq
x-onpress-realm: prod
x-ratelimit-limit: 120
x-ratelimit-remaining: 102
x-ratelimit-reset: 1793135732| Что | Предел | Ответ при превышении |
|---|---|---|
| Запросы по токену | 120 в минуту на пользователя, скользящее окно | 429 too_many_requests и Retry-After |
| Запросы из консоли | 120 в минуту на сессию | 429 too_many_requests и Retry-After |
| Неудачные попытки с токеном | 20 в минуту с одного адреса | 429 too_many_auth_failures и Retry-After |
| Попытки входа в консоль | 30 в минуту с одного адреса | 429 too_many_requests и Retry-After |
| Тело запроса в JSON | 10 МБ | 413 body_too_large |
| Разметка одного фрейма | 2 МБ | 413 frame_too_large |
| Одни пользовательские данные | 512 КБ | 413 dataset_too_large |
| Собственный CSS сайта | 256 КБ | 413 css_too_large |
| Файл медиа | 32 МБ в multipart/form-data; base64 в JSON — в пределах 10 МБ тела | 413 file_too_large |
| Список страниц | до 200 на страницу выдачи | больше не отдаётся |
| Список медиа | до 100 на страницу выдачи | больше не отдаётся |
Как повторять запрос после 429 — в разделе «Ошибки».