API-ключи

Публичное API PageCraft (/api/v1/*) авторизуется API-ключом. Интерфейс работает на cookie-сессии, и переиспользовать её для скриптов нельзя: ключ не зависит от браузера, не истекает вместе с сессией и отзывается отдельно.

Формат ключа

pb_ + 64 шестнадцатеричных символа

Например: pb_a1b2c3d4e5f6... — всего 67 символов. Ключ создаётся из 32 случайных байт, на сервере хранится только его SHA-256-хэш, поэтому показать ключ повторно невозможно — ни в интерфейсе, ни через API.

Ключ привязан к пользователю и видит ровно те же данные, что и его владелец в интерфейсе. Компрометация одного ключа не затрагивает других пользователей.

Как создать

1. Войдите в PageCraft.
2. Меню пользователя (аватар справа в шапке) → Настройки.
3. Панель API Ключи: введите название ключа и нажмите «Создать».
4. Скопируйте значение сразу — оно показывается один раз. Дальше в списке остаётся только префикс вида pb_a1b2c3... для опознания.

Название — свободная строка до 255 символов; удобно называть по месту использования: Claude Code, Cursor, CI.

В списке ключей видно, когда каждый использовался последний раз, — по этому полю удобно находить забытые ключи и удалять их.

Как передавать в запросах

Заголовок Authorization со схемой Bearer:

export API='https://page-craft.4partners.io/api/v1'
export KEY='pb_a1b2c3d4e5f6...'

curl -s -H "Authorization: Bearer $KEY" "$API/sites"

Других способов передачи нет: ключ в query-строке или в отдельном заголовке не принимается. Сервер опознаёт запрос как «ключевой» именно по префиксу Bearer pb_ — поэтому значение вставляется целиком, вместе с pb_.

Что вернётся без ключа или с плохим ключом

Ключ не передан:

{ "error": "API key required. Pass it via Authorization: Bearer <key>" }

Ключ передан, но не найден:

{ "error": "Invalid API key." }

Оба ответа — 401. Разбор остальных кодов — на странице Коды ошибок.

Отзыв ключа

В той же панели API Ключи — кнопка удаления рядом с ключом. Удаление необратимо и действует сразу: следующий запрос с этим ключом получит 401. Ротация делается в два шага — создать новый ключ, поменять его в потребителе, удалить старый.

Управление ключами из кода

Ключи живут во внутреннем контуре /api/*, который авторизуется cookie-сессией, а не ключом. То есть создать ключ ключом нельзя — это сделано намеренно, чтобы утёкший ключ не мог выписать себе новые.

Метод	Путь	Что делает
GET	/api/api-keys	список ключей (только префиксы)
POST	/api/api-keys	создать ключ; поле key есть только в этом ответе
DELETE	/api/api-keys/{id}	удалить ключ

Дальше

• REST API V1 — базовый URL, пагинация, формат ответов.
• Playbook: фабрика страниц — полный сценарий от выбора сайта до публикации.
• Скиллы: установка и список — если работать с API будет ИИ-агент, ключ понадобится ему.

Источники

• backend/src/Service/ApiKey/CreateApiKeyService.php — генерация и хранение ключа
• backend/src/Security/ApiKeyAuthenticator.php — разбор заголовка, ответы 401
• backend/src/Controller/ApiKey/* — эндпоинты /api/api-keys
• front/src/components/Settings/SettingsPage.tsx — панель «API Ключи»
• openapi/v1.json → components.securitySchemes.bearerAuth