> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Что такое персональный token доступа и как заменить системный token?
> Персональные token доступа обеспечивают аутентификацию в API управления, таких как управление балансом, логами и token, с разрешениями для отдельных scope, сроком действия и белыми списками IP. Устаревшие системные tokens планируется вывести из эксплуатации 2026-11-11.
## Краткий ответ
**Персональный access token** — это новые учетные данные для API управления APIYI. Он позволяет вашим скриптам и инструментам автоматизации вызывать API запроса баланса, запроса логов и управления tokens.
Он заменяет старый **системный token**. Вы можете **предоставлять только необходимые разрешения**, **задавать срок действия** и **ограничивать его списком разрешенных IP-адресов**. Каждый аккаунт может содержать до 20 tokens, поэтому вы можете выпускать по одному под каждую задачу.
**Устаревшие системные tokens планируется вывести из эксплуатации 2026-11-11 (UTC+8).** После этого вызовы API управления с системным token будут возвращать 401.
Мы проанализируем фактическое использование до наступления этой даты и, возможно, продлим срок, но рекомендуем перейти на персональный access token уже сейчас. Вам достаточно лишь заменить значение в заголовке `Authorization`. Ваш код останется прежним.
Персональные access tokens **не могут вызывать модели**. Для вызова моделей продолжайте использовать свой API-ключ (в консоли он называется «ключом модели» и начинается с `sk-`).
## Отличия от системного token
| | Устаревший системный token | Персональный token доступа |
| - | - | - |
| Права доступа | Полные права аккаунта | Выбор для каждого scope; чтение, запись и reveal-secret независимы |
| Количество | 1 на аккаунт | До 20 на аккаунт, по одному для каждой цели |
| Срок действия | Бессрочно | 30 / 90 / 180 / 365 дней, настраиваемый или бессрочно |
| Список разрешенных IP | Не поддерживается | IPv4, IPv6 и CIDR |
| Префикс | Нет фиксированного префикса | Начинается с `nap_` |
| Статус | Запланирован вывод из эксплуатации 2026-11-11 (UTC+8) | Рекомендуется |
## Как создать token
Войдите в консоль и перейдите на страницу профиля по адресу `api.apiyi.com/account/profile`. В разделе **Account Options** нажмите **Personal Access Tokens**, затем нажмите **Create Token** в правом верхнем углу.
Задайте понятное имя, отражающее назначение, например «скрипт сверки» или «мониторинг баланса». Срок действия по умолчанию составляет 30 дней, и token перестает работать после его окончания. **Мы рекомендуем выбрать более длительный период** (например, 365 дней), чтобы работа ваших скриптов неожиданно не прервалась.
Разделяйте несколько записей запятыми. Поддерживаются IPv4, IPv6 и CIDR. Оставьте поле пустым, если ограничения не требуются. **Список разрешенных адресов нельзя изменить после создания.** См. рекомендуемый порядок действий ниже.
Выбирайте только то, что используется вашим скриптом. См. таблицу ниже.
Нажмите **Create Token**, затем сразу скопируйте token и сохраните его в надежном месте.
## Какие разрешения выбрать
Существует три типа разрешений: чтение, запись и просмотр секрета. Каждое из них предоставляется отдельно. Запись не включает в себя чтение, а чтение не отображает открытый текст ключа.
| API, который вы хотите вызвать | Необходимое разрешение |
| - | - |
| [Запрос баланса](/ru/api-capabilities/balance-query) (`GET /api/user/self`) | Профиль · Чтение |
| [Запрос логов](/ru/api-capabilities/log-query) (`GET /api/log/self`) | Использование и личные записи · Чтение |
| [Управление token](/ru/api-capabilities/token-management): получение списка или просмотр API-ключей | Ключи моделей · Чтение |
| [Управление token](/ru/api-capabilities/token-management): создание, обновление или удаление API-ключей | Ключи моделей · Запись |
| [Управление token](/ru/api-capabilities/token-management): получение открытого текста API-ключа | Ключи моделей · Просмотр секрета |
Например, для ежедневной задачи сверки требуется только «Использование и личные записи · Чтение», а для мониторинга баланса — только «Профиль · Чтение».
**Действия, требующие проверки безопасности, такие как смена пароля или настроек двухфакторной аутентификации, по-прежнему необходимо выполнять после входа на веб-сайт.** Token персонального доступа не может выполнять их даже при наличии разрешения на запись.
Используйте один token для каждого скрипта и предоставляйте ему только те разрешения, которые используются этим скриптом. Когда скрипт выводится из эксплуатации или происходит утечка token, удалите этот конкретный token. Это никак не повлияет на остальные ваши скрипты.
## Безопасная настройка белого списка IP
Белый список нельзя отредактировать после создания. Чтобы изменить его, необходимо создать новый token. Мы рекомендуем следующий порядок действий:
1. **Создайте token без белого списка** и наладьте работу вашего скрипта.
2. Как только все заработает, **создайте production token с белым списком**. Включите в него все исходящие IP, которые могут использоваться: production-серверы, резервные серверы и сеть офиса, которая может понадобиться для устранения неполадок.
3. Переключитесь на production token и **удалите тестовый token без белого списка**.
Указывайте **публичные исходящие IP**, а не адреса локальных сетей. Если ваш исходящий IP меняется (как это часто бывает при домашнем подключении или в офисных сетях), не используйте белый список. Вместо этого предоставьте права только на чтение и установите более короткий срок действия.
## Как использовать
Использование такое же, как и с системным token. Поместите сам token в заголовок `Authorization`. Префикс `Bearer ` необязателен.
```bash theme={null}
curl --compressed -s 'https://api.apiyi.com/api/user/self' \
-H "Authorization: $APIYI_TOKEN"
```
Если скрипт в данный момент использует системный token, замените значение в его переменной окружения или конфиге на новый token.
## Распространенные ошибки
| HTTP-статус | Ответ | Причина и решение |
| - | - | - |
| 401 | `ACCESS_TOKEN_LEGACY_RETIRED`, `Legacy management tokens have been retired...` | Вы по-прежнему используете устаревший системный token после даты прекращения поддержки. Создайте personal access token, как описано выше. |
| 401 | `This access token may not be used from the current IP address.` | Запрос поступил с IP-адреса, не входящего в список разрешенных для этого token. Проверьте публичный исходящий IP-адрес вашего сервера. Список разрешенных адресов нельзя изменить, поэтому создайте новый token. |
| 403 | `ACCESS_TOKEN_SCOPE_DENIED`, `This endpoint is outside this access token's granted permissions.` | У token отсутствуют права доступа, необходимые для этого API. Создайте новый token с правами доступа из таблицы выше. |
| 401 | Недействительный token | Срок действия token истек или он был удален, либо кто-то изменил пароль, двухфакторную аутентификацию или passkey аккаунта. **Любое из этих трех изменений отзывает все personal access token аккаунта.** Создайте новый token. |
## Связанная документация
Проверяйте баланс своего аккаунта с помощью персонального token доступа
Получайте записи вызовов по диапазону времени для сверки
Создавайте, ротируйте и удаляйте API-ключи программно
Границы разрешений и предотвращение утечек API-ключей
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.