Авторизация
API проверяет токен или сессию и права на выбранный сайт. Первый токен и запрос — в гайде «Быстрый старт».
| Тема | Раздел |
|---|---|
| Токен в заголовке | Передать токен |
| Выпуск и удаление ключей | Управлять ключами |
| Сессия консоли | Передать сессию |
| Доступ к сайту | Права |
| Идентификатор сайта | Выбор сайта |
| Ограничения запросов | Лимиты |
Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.
Токен
Токен (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 API обновляет не чаще раза в минуту.
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
missing_token | 401 | нет ни Authorization: Bearer, ни X-OnPress-Key | добавить заголовок с токеном |
invalid_token | 401 | токен не той формы, неизвестен или отозван | выпустить ключ в консоли или через POST /me/api-keys |
too_many_auth_failures | 429 | больше 20 неудачных попыток за минуту с одного адреса | подождать Retry-After секунд и исправить токен |
Управлять API-ключами
В консоли ключи находятся в «Настройки → API-ключи». Новый ключ не отзывает прежние, удалить можно любой. Кнопка «Промпт для AI» сама выпускает отдельный ключ «Для промптов AI» и подставляет его в промпт. Параметры, ответы и ошибки операций описаны в справочнике пользователей.
| Метод | Путь | Действие |
|---|---|---|
GET | /me/api-keys | Получить список ключей |
POST | /me/api-keys | Выпустить ключ |
DELETE | /me/api-keys/{id} | Удалить ключ |
POST | /me/api-keys/ai | Получить ключ для промптов AI |
Чтобы сменить ключ у скрипта или агента, выпустите новый, поставьте его и удалите прежний.
Сессия консоли
Консоль https://onpress.pro/dashboard/ ходит в тот же API не токеном, а сессионной кукой после входа почтой, через Google или Telegram. Эндпоинты принимают и куку, и токен; если в запросе есть и то и другое, а кука истекла, API проверяет токен. Запрос с кукой API принимает только с адреса консоли, иначе отвечает 403 cross_origin. Агенту и скрипту кука не нужна, вход и продление сессии описаны на странице «Состояние API».
Права
Роль одна — администратор сайта: ему открыты все эндпоинты сайта, и чтение, и запись страниц, фреймов, данных, меню, стилей, настроек, языков, SEO, медиа и пользователей сайта. Участник сайта без прав администратора получает 403 insufficient_role на любом эндпоинте сайта, включая чтение, а чужой сайт отвечает 404 site_not_found. Главный сайт сети onpress.pro подчиняется тому же правилу: записывает в него только его администратор. Эндпоинты сети — /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; он выдается при создании сайта и больше не меняется, поэтому его можно хранить в скриптах и закладках. Идентификатор случайный: по одному id нельзя вычислить соседний. Под этим префиксом живут все эндпоинты сайта: /pages, /data, /frames, /data/menus, /media, /users, /data/docs.sidebar, /data/seo, /redirects и остальные из справочника; настройки, главную страницу и языки сайта отдают системные данные /data/site.settings, /data/site.front_page и /data/site.languages. Например, список системных данных сайта:
curl -s "$API/site/$SITE/data/system" \
-H "Authorization: Bearer $OP_TOKEN"
Ответ на таком адресе называет сайт заголовком X-OnPress-Site-Id, многие эндпоинты — еще и полем site_id; внутренний номер сайта в нем не появляется. Несуществующий и чужой сайт отвечают одинаково — 404 site_not_found с одним и тем же текстом, поэтому id сайтов нельзя перебрать.
| Параметр | Где | Тип | Описание |
|---|---|---|---|
siteId | путь /site/{siteId}/… | строка | id сайта из девяти знаков |
siteId приходит в ответе POST /sites при создании сайта и полем site_id в GET /sites, GET /sites/{id} и GET /data; в консоли он виден в разделе «Данные», в адресе эндпоинтов сайта. /sites/{id} принимает в пути siteId или домен сайта.
| Код | HTTP | Когда | Что делать |
|---|---|---|---|
site_not_found | 404 | сайта с таким siteId нет или вы не его администратор | проверить siteId в GET /data или в консоли |
insufficient_role | 403 | вы участник сайта, но не администратор | попросить администратора сайта выдать права |
cross_origin | 403 | запрос с кукой сессии пришел не с адреса консоли | отправить запрос с токеном |
Лимиты
Каждый ответ эндпоинта с авторизацией несет заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset — unix-время, когда освободится самый старый запрос окна. Лимит токена считается на пользователя, а не на токен, и перевыпуск его не обнуляет; у каждой сессии консоли свое окно, отдельное от токена, поэтому скрипт, выбравший лимит токена, не мешает тому же пользователю работать в консоли. Счетчик живет в памяти процесса API, и перезапуск сервиса его обнуляет. Например, посмотреть остаток лимита:
curl -s -D - -o /dev/null "$API/site/$SITE/data/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 — в разделе «Ошибки».