Документация

Авторизация

Все методы управления ассистентом работают по личному ключу пользователя user_…. Ключ открывает ваши ассистенты и те, что вам расшарили.

Markdown
Открыть в ИИ

Личный ключ

Методы управления ассистентами (/assistants/…, /agents/…, /models/catalog) принимают личный ключ пользователя. Он выглядит так:

user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Префикс user_ и 40 случайных символов. У пользователя один ключ, он действует бессрочно, пока его не перевыпустят. Запросы по ключу выполняются от имени его владельца с теми же правами, что у него в дашборде.

Где выпустить

В дашборде: «Настройки → API ключ», адрес https://framesuite.app/dashboard/settings/api-key.

ДействиеЧто происходит
«Выпустить ключ»Появляется, если ключа ещё нет. Создаёт ключ и показывает его
«Показать» и «Копировать»Ключ хранится в открытом виде, поэтому его можно посмотреть в любой момент, а не только сразу после выпуска
«Перевыпустить» (опасная зона)Выдаёт новый ключ. Старый перестаёт работать сразу: все скрипты с ним начнут получать 401

Страница доступна любому зарегистрированному пользователю дашборда. Анонимным гостям и отключённым аккаунтам (disabled) она закрыта. Если аккаунт отключают, уже выпущенный ключ отвечает 403 Account disabled, пока аккаунт не включат обратно.

Как передать ключ

Подходит любой из трёх способов. Если передано несколько, берётся первый по порядку в таблице.

СпособПример
Заголовок AuthorizationAuthorization: Bearer user_…
Заголовок X-API-KeyX-API-Key: user_…
Параметр строки запроса api_key?api_key=user_…
curl -s "$BASE/assistants" \
  -H "Authorization: Bearer $KEY"
curl -s "$BASE/assistants/$ASSISTANT/api-key" \
  -H "X-API-Key: $KEY"
curl -s "$BASE/assistants/$ASSISTANT/access?api_key=$KEY"

Параметр api_key оседает в логах веб-серверов, прокси и в истории браузера. Используйте его только там, где заголовок поставить нельзя.

Ошибки авторизации

Ключ проверяется до обращения к ассистенту, поэтому эти ответы приходят на любой метод одинаково. Первые три — с кодом 401, последний — 403.

КогдаТело
Ключ не передан{"error": "API token is required", "message": "Provide user API token via Authorization header (Bearer token), X-API-Key header, or api_key query parameter"}
Ключ не начинается с user_ (например, передали ключ ассистента site_…){"error": "Invalid token format", "message": "Token must start with \"user_\""}
Такого ключа нет: опечатка или ключ перевыпущен{"error": "Invalid API token"}
Аккаунт владельца ключа отключён (status = disabled), код 403{"error": "Account disabled", "message": "The account that owns this API token is disabled"} — ключ снова заработает, когда аккаунт включат
curl -s "$BASE/assistants" \
  -H "Authorization: Bearer user_nope"
{ "error": "Invalid API token" }

Какие ассистенты открывает ключ

Ключ видит два набора ассистентов:

НаборЧто можно
Свои (вы владелец, project.user_id — project здесь объект ассистента, имя ключа историческое)Всё, включая удаление ассистента
Расшаренные вам (ваш id в shared_user_ids, см. Доступ)Всё то же, что владельцу: настройки, агенты, пейволл, деньги, ключ ассистента. Кроме удаления ассистента и управления доступом других людей — можно только убрать себя

GET /assistants возвращает оба набора. Чужой ассистент для ключа не существует: методы ассистента отвечают 404 {"error": "Project not found or access denied"} — и на чужой, и на несуществующий id, чтобы по ответу нельзя было понять, есть ли такой ассистент.

curl -s "$BASE/assistants/1" \
  -H "Authorization: Bearer $KEY"
{ "error": "Project not found or access denied" }

Так же отвечают все разделы, включая агентов и версии: правило доступа одно для всего API, отдельных прав у администраторов площадки по личному ключу нет.

Ключ ассистента site_…

У каждого ассистента есть второй ключ — ключ ассистента вида site_… (32 символа после префикса). Он открывает только методы чатов этого ассистента: создать чат, отправить сообщение, прочитать историю, список чатов. Методы управления его не принимают — ответят 401 Invalid token format.

Личный ключ user_…Ключ ассистента site_…
Кому принадлежитПользователюОдному ассистенту
Что открываетУправление всеми вашими и расшаренными ассистентамиТолько чаты одного ассистента
Где взять«Настройки → API ключ»GET /assistants/{assistantId}/api-key
Как сменить«Перевыпустить» в дашбордеPOST /assistants/{assistantId}/api-key/regenerate

Ключ ассистента передаётся теми же тремя способами. Методы чатов — Чаты по ключу ассистента, получение и перевыпуск ключа — Ассистенты.

Дальше