---
id: auth-create-token
title: "POST /api/profile/tokens — Создать API-токен"
domain: auth
kind: api-method
http: "POST /api/profile/tokens"
---

# POST /api/profile/tokens — Создать API-токен {#auth-create-token}

## Сводка

| Поле | Значение |
|---|---|
| **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`) — _уточнить причины вручную_

Это операция выдачи самого 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. Подробнее про границы — [Конвенции](../../../shared/conventions.md#conventions) и [путеводитель для агента](../../../guides/agents.md).

**Пример запроса (из браузера, cookie-сессия):**

```bash
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`:**

```json
{
  "id": "aaaa1111-...",
  "name": "CI-бот",
  "prefix": "tak_",
  "scope": "read_write",
  "expires_at": null,
  "token": "tak_xZ9...секрет показывается один раз..."
}
```

Получив `token`, агент проверяет, от чьего имени он работает, через [whoami](users-me.md#auth-users-me) (`GET /api/users/me`) — это базовая точка self-discovery: владелец токена + его активная организация.

<!-- gen:start:related -->
## Связанные
- Экраны: [Профиль](../screens/profile.md#auth-screen-profile)
- [Конвенции](../../../shared/conventions.md#conventions) · [Роли](../../../shared/roles.md#roles) · [Ошибки](../../../shared/errors.md#errors) · [Глоссарий](../../../shared/glossary.md#glossary)
<!-- gen:end:related -->

---

Human view: https://docs.vnimanie.ai/specbuilder/v1/domains/auth/api/create-token/