API-ключи — Справочник API

Управление учетными данными данного аккаунта.

Метод	Путь	Описание
`GET`	`/v1/api-keys`	Список ключей аккаунта
`POST`	`/v1/api-keys`	Создание API-ключа
`PATCH`	`/v1/api-keys/{keyId}`	Редактирование ключа
`DELETE`	`/v1/api-keys/{keyId}`	Отзыв ключа

Сгенерировано из openapi.yaml во время сборки. Базовый URL https://api.tenergy.me/v1 или https://api-nile.tenergy.me/v1 в сети Nile (Окружения). Каждый запрос ниже подписывается в соответствии с разделом Аутентификация, если в строке Аутентификация не указано иное.

Список ключей аккаунта

GET /v1/api-keys · listApiKeys

Аутентификация: API-ключ (HMAC).

Секреты никогда не возвращаются этим эндпоинтом — секрет отдается в ответе ровно один раз при создании. Значение key, отображаемое здесь — это публичный идентификатор, передаваемый в заголовке X-API-KEY.

Ответы

Статус	Значение
`200`	OK
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`500`	Ошибка на нашей стороне.

Поля ответа

Поле	Тип	Обязательное	Описание
`data`	array of object (ApiKey)	да
`data[].id`	string	да
`data[].key`	string	да	Публичный идентификатор для заголовка `X-API-KEY`. Не является секретом.
`data[].label`	string	да
`data[].scopes`	array of enum (13 values, ApiKeyScope)	да
`data[].ip_allowlist`	array of string
`data[].is_active`	boolean	да
`data[].last_used_at`	string (date-time) \| null		Время последней подписи запроса данным ключом. Записывается не чаще одного раза в минуту на ключ, отвечая на вопрос «используется ли ключ», а не «до секунды, когда».
`data[].last_used_ip`	string \| null		IP-адрес источника последнего запроса. `null`, пока ключ не использовался.
`data[].expires_at`	string (date-time) \| null
`data[].created_at`	string (date-time)	да
`limit`	integer	да	Сколько активных ключей может иметь аккаунт одновременно. Продуктовый лимит, ограничивающий число учетных данных. При превышении `POST /api-keys` возвращает `3017 api_key_limit_reached`; отзыв ключа сразу освобождает слот.
`used`	integer	да	Текущее количество активных ключей (отозванные и истекшие не учитываются).

Создание API-ключа

POST /v1/api-keys · createApiKey

Аутентификация: API-ключ (HMAC) или bootstrap-токен.

Создает ключ и возвращает его секрет один раз. Секрет не сохраняется в восстановимом виде; в случае утери удалите ключ и создайте новый.

Первый ключ аккаунта создается с помощью bootstrap-токена из сценария регистрации; каждый последующий — с помощью существующего ключа с правом keys.create.

Также доступно на непополненном аккаунте (с 2026-09-26), чтобы интеграция могла прочитать депозитный адрес с новым ключом и пополнить баланс в автоматическом режиме.

Поле scopes обязательно и не имеет значения по умолчанию. API намеренно не использует стандартный набор прав: полномочия ключа определяются владельцем аккаунта. Запрос без scopes отклоняется с ошибкой 2001 validation_failed, и ни клиентская библиотека, ни агент, ни форма интерфейса не могут подставить их за владельца.

Единый словарь разрешений

Разрешения именуются по схеме area.action и образуют единый список для всей платформы. Ниже перечислены права, доступные для API-ключа в v1. Остальные имена словаря — balance.withdraw, billing.write, invoices.read, referral.read, referral.withdraw, team.read, team.invite, team.remove, team.grant, settings.write, audit.read — предназначены для управления командой в интерфейсе, но недоступны для API-ключей в v1.

Scope	Что открывает
`prices.read`	`POST /estimate/transfer` (`GET /prices`, `GET /estimate` и `GET /resources/{address}` публичны и не требуют scope)
`balance.read`	`GET /account`, `GET /balance` — балансы и счетчики за все время
`balance.topup_address`	`GET /deposit-addresses` — депозитный адрес аккаунта и архивные адреса
`orders.read`	`GET /orders` (включая CSV), `GET /orders/{id}`, `GET /batches…`, `GET /quotes/{id}`, `GET /account/stats`
`orders.create`	`POST /orders`, `POST /quotes`, `POST /batches`, `POST /batches/{id}/cancel` — тратит средства
`orders.reclaim`	`POST /orders/{id}/reclaim` — досрочный отзыв аренды без возврата средств
`subscriptions.read`	`GET /subscriptions…`
`subscriptions.write`	создание, изменение, отмена подписок — фиксирует регулярные списания
`webhooks.read`	`GET /webhooks…`, включая `GET /webhooks/{id}/deliveries`
`webhooks.write`	создание, изменение, удаление, ротация и тестирование эндпоинтов вебхуков
`keys.read`	`GET /api-keys`
`keys.create`	`POST /api-keys`, `PATCH /api-keys/{id}` — ключ с этим правом может расширять права аккаунта
`keys.revoke`	`DELETE /api-keys/{id}` — может мгновенно остановить рабочую интеграцию

Эндпоинты GET /ledger, GET /account/addresses и GET /session/history относятся к операциям сессии панели управления; ни один scope не дает доступа к ним по API-ключу.

Ключ может быть создан только с теми scopes, которыми уже обладает ключ вызывающей стороны, поэтому keys.create нельзя использовать для эскалации привилегий. Ключ, созданный через bootstrap-токен, может содержать любые доступные для ключей scopes, поскольку подписывающий адрес является владельцем аккаунта.

Тело запроса

JSON (ApiKeyRequest), обязательно.

Поле	Тип	Обязательное	Описание
`label`	string		Необязательно. Если не указано, ключ именуется `Key N` по следующему свободному индексу. Метка — это название, а не право доступа.
`scopes`	array of enum (13 values, ApiKeyScope)	да	Обязательно, без значения по умолчанию. Названия прав из единого словаря платформы; см. описание выше.
`ip_allowlist`	array of string		Разрешенные IP-адреса (IPv4/IPv6 или CIDR-блоки). Пустой список разрешает запросы с любых IP — допустимо для чтения, не рекомендуется для ключей с правами расходования средств.
`expires_at`	string (date-time) \| null		Время автоматического отзыва ключа. `null` для бессрочного ключа.

Пример тела запроса из контракта (значения для иллюстрации):

json

{
  "label": "grafana exporter",
  "scopes": ["balance.read","orders.read"],
  "ip_allowlist": ["203.0.113.10"]
}

Ответы

Статус	Значение
`201`	Создан. `secret` возвращается только один раз в этом ответе.
`400`	Некорректный запрос — невалидный JSON, неизвестное поле или неверный тип.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`403`	Аутентифицирован, но данный ключ не имеет прав на это действие.
`409`	`3017 api_key_limit_reached` — достигнут лимит активных ключей. Проверьте `details.limit` и `details.used`; отзовите неиспользуемый ключ.
`422`	Синтаксически корректный запрос, но действие невозможно.
`500`	Ошибка на нашей стороне.

Поля ответа

Поле	Тип	Обязательное	Описание
`id`	string	да
`key`	string	да	Публичный идентификатор для заголовка `X-API-KEY`. Не секрет.
`label`	string	да
`scopes`	array of enum (13 values, ApiKeyScope)	да
`ip_allowlist`	array of string
`is_active`	boolean	да
`last_used_at`	string (date-time) \| null		Время последней подписи запроса. Обновляется не чаще раза в минуту.
`last_used_ip`	string \| null		IP-адрес последнего запроса. `null` до первого использования.
`expires_at`	string (date-time) \| null
`created_at`	string (date-time)	да
`secret`	string	да	Секрет HMAC, 256 бит, показывается один раз. Префикс `sk_live_…` в production и `sk_test_…` в Nile. Не восстановим: при утере отзовите ключ и создайте новый.

Редактирование ключа

PATCH /v1/api-keys/{keyId} · updateApiKey

Аутентификация: API-ключ (HMAC).

Изменение параметров label, ip_allowlist, is_active или scopes. Сужение scopes вступает в силу немедленно. Расширение прав подчиняется тому же правилу: вызывающий ключ должен сам обладать всеми добавляемыми правами.

Параметры

Параметр	Где	Тип	Обязательный	Описание
`keyId`	path	string	да

Тело запроса

JSON (ApiKeyPatch), обязательно.

Поле	Тип	Обязательное	Описание
`label`	string
`scopes`	array of enum (13 values, ApiKeyScope)
`ip_allowlist`	array of string
`is_active`	boolean
`expires_at`	string (date-time) \| null

Ответы

Статус	Значение
`200`	Обновлен
`400`	Некорректный запрос — невалидный JSON, неизвестное поле или неверный тип.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`403`	Аутентифицирован, но данный ключ не имеет прав на это действие.
`404`	Объект не найден или принадлежит другому аккаунту.
`422`	Синтаксически корректный запрос, но действие невозможно.
`500`	Ошибка на нашей стороне.

Поля ответа (`ApiKey`)

Поле	Тип	Обязательное	Описание
`id`	string	да
`key`	string	да	Публичный идентификатор для заголовка `X-API-KEY`. Не секрет.
`label`	string	да
`scopes`	array of enum (13 values, ApiKeyScope)	да
`ip_allowlist`	array of string
`is_active`	boolean	да
`last_used_at`	string (date-time) \| null		Время последней подписи запроса данным ключом.
`last_used_ip`	string \| null		IP-адрес источника последнего запроса.
`expires_at`	string (date-time) \| null
`created_at`	string (date-time)	да

Отзыв ключа

DELETE /v1/api-keys/{keyId} · deleteApiKey

Аутентификация: API-ключ (HMAC).

Мгновенное и необратимое действие. Запросы в обработке, подписанные этим ключом, сразу отклоняются; созданные им ранее заказы не затрагиваются и продолжают исполняться.

Ключ не может удалить сам себя во избежание потери доступа к аккаунту, если это был последний ключ. Отзыв собственного ключа осуществляется через панель управления.

Параметры

Параметр	Где	Тип	Обязательный	Описание
`keyId`	path	string	да

Ответы

Статус	Значение
`204`	Отозван. Тело ответа пустое.
`401`	Отсутствуют, некорректны или отклонены учетные данные.
`403`	Аутентифицирован, но данный ключ не имеет прав на это действие.
`404`	Объект не найден или принадлежит другому аккаунту.
`500`	Ошибка на нашей стороне.

API-ключи — Справочник API

Список ключей аккаунта

Ответы

Поля ответа

Создание API-ключа

Единый словарь разрешений

Тело запроса

Ответы

Поля ответа

Редактирование ключа

Параметры

Тело запроса

Ответы

Поля ответа (ApiKey)

Отзыв ключа

Параметры

Ответы

Поля ответа (`ApiKey`)