POST /api/profile/tokens — Создать API-токен
Сгенерировано из матриц + кода. Правки вносить в источники (
docs/matrices/,server/routes/), не здесь.
| Поле | Значение |
|---|---|
| HTTP | POST /api/profile/tokens |
| Auth | — |
| Scope токена | read_write |
| PG-функции | api.create_api_token |
| Таблицы | api_token |
| SRM | SRM-338 |
| RP (права) | RP-164 |
| Файл роута | server/routes/profile.js |
| Статус | done |
Аргументы запроса (best-effort из хендлера; путь-параметры опущены):
| Аргумент | Где | Обяз. | Заметка |
|---|---|---|---|
expiresAt | body | подтвердить | |
name | body | подтвердить | |
scope | body | подтвердить |
Коды ответов/ошибок (из хендлера): 201, 400 (+ 200) — уточнить причины вручную
Для человека
Как открыть: кнопка со своим именем в правом верхнем углу → экран «Профиль» → раздел «Токены API» → впишите название, выберите scope в выпадающем списке и нажмите «Создать токен».
Выпускает API-токен — ключ, по которому агент ходит в систему от вашего имени и в рамках ваших прав. Это и есть «врата» агентного доступа: без токена ни один внешний агент к вашим данным не подключится.
Что задаёте при создании:
- Название — чтобы потом отличать токены в списке (например, «CI-бот»).
- Scope — «Только чтение» (агент сможет лишь смотреть) или «Чтение + запись» (агент сможет ещё и создавать, менять, удалять — но всё так же в пределах ваших прав). Для записи интерфейс отдельно предупреждает: выдавайте такой токен только доверенным агентам.
Секрет (tak_…) показывается ровно один раз, сразу после создания, с кнопкой «Копировать». Закрыли — больше его не увидеть; потеряли — отзовите и выпустите новый. Токен наследует ваши права, но не даёт операций администратора платформы и администратора организации, и сам токеном управлять не может.
Кто может. Выпустить свой токен может любой вошедший пользователь (RP-164, permission = self): сотрудник, менеджер спейса, наблюдатель, администратор организации. Гость токенов не выпускает.
Для агента
Это операция выдачи самого Bearer-токена, поэтому она выполняется под cookie-сессией, не под токеном: путь /api/profile/tokens закрыт для Bearer-токенов в agent-gate (server/auth/agentGate.js) — токен-актор не может породить ещё один токен (анти-эскалация). Вызов с Authorization: Bearer tak_... вернёт 403; создавать токен нужно из браузера с cookie-сессией.
Что получает на выходе агент — это секрет вида tak_<32 байта base64url>, который дальше подставляется в заголовок Authorization: Bearer tak_... всех агентных вызовов. Секрет приходит в ответе один раз (поле token); сервер хранит только его хэш.
Тело запроса (JSON):
| Поле | Тип | Обяз. | Назначение |
|---|---|---|---|
name | string | нет | Метка токена для списка, обрезается до 100 символов |
scope | string | нет | read (только GET) или read_write (GET + мутации). Любое другое значение → безопасный дефолт read |
expiresAt | string | null | нет | Срок годности (ISO-дата) или null — бессрочный |
Scope определяет потолок токена: read — только чтение, read_write — чтение плюс мутации, но всегда в пределах роли владельца и минус операции site-admin и часть операций org-admin, закрытые на уровне gate. Подробнее про границы — Конвенции и путеводитель для агента.
Пример запроса (из браузера, cookie-сессия):
curl -X POST https://specbuilder.vnimanie.ai/api/profile/tokens \ -b cookies.txt \ -H "Content-Type: application/json" \ -d '{"name":"CI-бот","scope":"read_write"}'Ответ 201:
{ "id": "aaaa1111-...", "name": "CI-бот", "prefix": "tak_", "scope": "read_write", "expires_at": null, "token": "tak_xZ9...секрет показывается один раз..."}Получив token, агент проверяет, от чьего имени он работает, через whoami (GET /api/users/me) — это базовая точка self-discovery: владелец токена + его активная организация.