# Токены и области доступа

> Как создать API-токен Slicer, выбрать области доступа, срок и лимит расходов, где хранить токен и как его отозвать.

Источник: https://docs.slicer.media/api/authentication/

Каждый запрос к API подписывается токеном в заголовке `Authorization: Bearer`. Токен принадлежит вашему аккаунту и действует от вашего имени, но только в пределах выбранных **областей доступа** и **лимита расходов**. Так скрипт отчётов получает доступ «только чтение», а сервис автоматического монтажа не потратит больше заданного бюджета.

## Создать токен

### 1. Откройте раздел для разработчиков

**Профиль** → «Для разработчиков» в веб-приложении или в приложении для iPhone, iPad и Mac. Подробно об экране — в руководстве [Для разработчиков: токены и приложения](https://docs.slicer.media/guide/account/developers/).

### 2. Нажмите «Создать токен» и заполните форму

-   **Название** — до 60 знаков, чтобы отличать токены в списке: «Сервер рассылки», «Ноутбук».
-   **Доступ** — один из наборов или свои области (ниже).
-   **Срок** — 30, 90, 365 дней или без срока.
-   **Лимит расходов** — без лимита, 50, 200, 1000 токенов в месяц или своё число.

Создать токен можно только из приложения Slicer после входа в аккаунт — другим токеном его не выпустить. Если вы давно не вводили пароль, приложение попросит подтвердить, что это вы.

### 3. Скопируйте токен

Токен показывается **один раз**. В Slicer хранится только его хэш, поэтому показать токен повторно нельзя — если он потерялся, отзовите его и создайте новый. На почту аккаунта придёт письмо «Создан API-токен» с названием, доступом и сроком.

Действующих токенов на аккаунт — не больше 20.

## Передать токен в запросе

Терминал:

```bash
curl https://api.slicer.media/v1/me \
  -H "Authorization: Bearer $SLICER_TOKEN"
```

API принимает токен только в заголовке. Cookie и параметры адреса для входа не используются, поэтому браузерная сессия Slicer не даёт доступа к `/v1`.

## Области доступа

Область — это право на группу действий. Эндпоинт требует одну или несколько областей; какие именно — указано в [справочнике](https://docs.slicer.media/api/reference/) у каждого эндпоинта.

| Область | Что разрешает |
| --- | --- |
| `account:read` | **Аккаунт и баланс** — Видеть имя, баланс токенов и историю операций |
| `projects:read` | **Видеть проекты** — Проекты, этапы, версии, текст ролика и скачивание готовых роликов |
| `projects:write` | **Менять проекты** — Загружать материалы, править ролики, менять стиль, выбирать версию, экспортировать и удалять проекты — бесплатно |
| `montage:run` | **Запускать монтаж — тратит токены** — Монтаж, пересборка, повтор, ИИ-помощник и перевод субтитров. Цена всегда подтверждается перед запуском |
| `publish` | **Публиковать в соцсети** — Видеть подключённые соцсети и публиковать в них ролики |
| `webhooks` | **Вебхуки** — Добавлять адреса для уведомлений о готовых роликах и публикациях |

Наборы в окне создания токена: **Только чтение** — `account:read`, `projects:read` · **Монтаж** — `account:read`, `projects:read`, `projects:write`, `montage:run` · **Полный доступ** — `account:read`, `projects:read`, `projects:write`, `montage:run`, `publish`, `webhooks`

При создании токена удобно выбрать набор:

| Набор | Области | Для чего |
| --- | --- | --- |
| «Только чтение» | `account:read`, `projects:read` | отчёты, дашборды, резервные копии роликов |
| «Монтаж» | \+ `projects:write`, `montage:run` | автоматизация монтажа и правок; набор по умолчанию для ИИ-агентов |
| «Полный доступ» | все шесть, включая `publish` и `webhooks` | собственный сервис публикации с уведомлениями |

Каталог стилей (`GET /v1/styles`), пресеты экспорта и оценка цены (`POST /v1/estimate`) доступны с любой областью.

> **Важно.** Без области `montage:run` токен не может потратить ни одного токена с баланса: монтаж, пересборка, повтор, субтитры из речи, ИИ-помощник и перевод субтитров ему недоступны. Создать бесплатный проект без ИИ-режиссёра (`mode: "manual"`), править его и экспортировать можно и без неё — хватает `projects:write`. Для скриптов, которым платные функции не нужны, не выдавайте эту область.

## Срок действия

Срок выбирается при создании: 30, 90 или 365 дней, или без срока. За 7 дней до окончания на почту аккаунта придёт письмо. После окончания срока запросы получают `401 token_expired`; продлить токен нельзя — создайте новый и замените его в своей программе.

## Лимит расходов

Лимит — сколько токенов этот API-токен может потратить за календарный месяц (по UTC). Учитываются все операции, запущенные этим токеном: идущие (зарезервированные) и завершённые. Если операция отменилась или не получилась и резерв вернулся на баланс, она в лимит не идёт.

-   Сколько осталось, видно в ответе `GET /v1/me` (`token.spendLimit`, `token.spentThisMonth`) и в каждой цене `Quote` (`spendLimitLeft`).
-   Операция, которая не помещается в лимит, не запускается: `402 spend_limit_exceeded`. Баланс аккаунта при этом может быть достаточным.
-   Лимит меняется в списке токенов без перевыпуска токена.

Лимит дополняет подтверждение цены: каждая платная операция сначала называет цену и запускается только с `confirmCost` ([Монтаж и цена](https://docs.slicer.media/api/montage/)).

## Форматы секретов

Все секреты Slicer узнаются по префиксу. После префикса — 43 случайных символа (256 бит) и 6 символов контрольной суммы: опечатку или подделку сервер отсекает ещё до поиска токена, а сканеры секретов в репозиториях находят токены Slicer без запроса к нам.

| Префикс | Что это | Срок |
| --- | --- | --- |
| `slc_` | API-токен из профиля | 30, 90, 365 дней или без срока |
| `slc_oat_` | токен доступа OAuth — выдаётся приложениям, которые вы подключили (например, ИИ-агентам) | 1 час |
| `slc_ort_` | токен обновления OAuth — приложение меняет его на новый токен доступа | 60 дней, при каждом обмене — новый |
| `slc_ul_` | секрет одноразовой ссылки на загрузку в `uploadUrl` | до 1 часа, один файл |
| `whsec_` | секрет подписи вебхука | пока существует вебхук |

## Хранение токена

-   Держите токен в переменной окружения или менеджере секретов. Не вставляйте его в код и не коммитьте в репозиторий.
-   **Не используйте токен в браузере и мобильных приложениях для чужих пользователей.** API отвечает на запросы с любого сайта (CORS без cookie), но токен в коде страницы может прочитать кто угодно — это ответственность владельца токена. Делайте запросы со своего сервера.
-   Одному сервису — один токен с нужным минимумом областей. Так утечку легко закрыть, не трогая остальное.
-   В списке токенов видны дата последнего использования и расход за месяц — незнакомая активность повод отозвать токен.

## Отзыв токена

Отозвать токен можно в любой момент в «Для разработчиков» — кнопка «Отозвать». Следующий запрос с ним получит `401 token_revoked`. Токены отзываются и автоматически: при удалении аккаунта и при его блокировке.

## Ошибки входа

| Статус | Код | Что случилось |
| --- | --- | --- |
| 401 | `unauthorized` | нет заголовка `Authorization: Bearer` |
| 401 | `invalid_token` | токен не найден или с ошибкой в символах |
| 401 | `token_revoked` | токен отозван или приложение отключено от аккаунта |
| 401 | `token_expired` | срок токена истёк |
| 403 | `insufficient_scope` | у токена нет области, нужной эндпоинту; недостающие области — в тексте ошибки |
| 503 | `api_disabled` | публичное API временно выключено |

При ошибках 401 и 403 ответ содержит заголовок `WWW-Authenticate` с причиной (`error="invalid_token"` или `error="insufficient_scope"` и нужными областями) — по нему ошибку разбирают и OAuth-клиенты.

## Токены OAuth

Приложения, которые работают от имени пользователя, — например, ИИ-агенты через [MCP-сервер](https://docs.slicer.media/mcp/) — получают токен не вручную, а через OAuth 2.1: пользователь входит в Slicer в браузере и разрешает доступ в окне согласия. Такой токен доступа (`slc_oat_…`) работает и с `/v1`, с теми же областями и лимитом расходов, что выбраны в окне согласия. Подробно — [Вход: OAuth и токен](https://docs.slicer.media/mcp/authentication/).

## Что дальше

[Быстрый стартПервый ролик через API за 10 минут.](https://docs.slicer.media/api/quickstart/)[ОшибкиФормат ошибок и что делать с каждым кодом.](https://docs.slicer.media/api/errors/)[ЛимитыСколько запросов в минуту принимает API.](https://docs.slicer.media/api/rate-limits/)