# Аутентификация

Для аутентифицированных вызовов передавайте ключ в заголовке `X-Api-Key`. Выберите тип ключа и права для нужного API; публичные операции, отмеченные в справочнике, ключа не требуют.

Заголовок `X-Api-Key`
Четыре типа ключей
Минимум привилегий
Отзыв и ротация в любой момент

## Ключи по сервисам 

У каждого сервиса свой тип ключа, ограниченный либо одним проектом, либо всем пространством. Аутентификация у всех одна - ключ передаётся в заголовке `X-Api-Key` и несёт фиксированный набор прав, выбранный при создании. Выберите ключ, чтобы увидеть детали:

API-ключ

Platform API - данные и операции блокчейна для одного проекта.

vilna_api_, В рамках проекта

| Поле | Значение |
|  --- | --- |
| **Префикс** | `vilna_api_` |
| **Область** | Один проект |
| **Эндпоинт** | `https://api.vilna.io/v2` |
| **Заголовок** | `X-Api-Key` |


Используется для адресов, транзакций, балансов, событий и счетов. Создаётся на странице **API-ключей** проекта.

Примеры запросов и форму отправки см. в операции [Список сетей](/ru/apis/platform/api/blockchain/list-blockchains).

RPC-ключ

Прямой доступ к узлам блокчейна во всех сетях.

vilna_rpc_, В рамках пространства

| Поле | Значение |
|  --- | --- |
| **Префикс** | `vilna_rpc_` |
| **Область** | Всё пространство |
| **HTTP** | `https://rpc.vilna.io` · заголовок `X-Api-Key` |
| **gRPC** | `grpc.vilna.io:443` · метаданные `x-api-key` |


Один ключ открывает доступ ко всем поддерживаемым сетям - сеть указывается в пути запроса (или в метаданных gRPC). Создаётся в **настройках пространства**.

```bash
export VILNA_RPC_KEY="<rpc-key>"
curl "https://rpc.vilna.io/ethereum" \
  -H "X-Api-Key: $VILNA_RPC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

Список сетей не требует ключа: `GET https://rpc.vilna.io/chains`.

Управляющий ключ

Администрирование пространств, проектов, участников и ключей.

vilna_mgt_, В рамках пространства

| Поле | Значение |
|  --- | --- |
| **Префикс** | `vilna_mgt_` |
| **Область** | Всё пространство |
| **Эндпоинт** | `https://mgmt.vilna.io/v1` |
| **Заголовок** | `X-Api-Key` |


Используется для [операций Management API](/ru/apis/mgmt/api) в пределах своего рабочего пространства и выданных прав, включая управление API/RPC-ключами. Создайте рабочее пространство и управляющий ключ в личном кабинете. Действия, требующие пользовательской сессии, описаны в разделе [Права доступа](/ru/apis/permissions#management-key-limits).

Примеры запросов и форму отправки см. в операции [Список проектов рабочего пространства](/ru/apis/mgmt/api/project/list-workspace-projects).

VKS-ключ

Согласование и подпись транзакций с участием узлов подписи.

vilna_vks_, В рамках пространства

| Поле | Значение |
|  --- | --- |
| **Префикс** | `vilna_vks_` |
| **Область** | Всё пространство |
| **Эндпоинт** | `https://vks.vilna.io/v1` |
| **Заголовок** | `X-Api-Key` |
| **Право** | `vks:access` для всех публичных операций |


Выпускайте ключ в личном кабинете. Ключи Platform, RPC и Management его не заменяют; публичный Management API не выпускает VKS-ключи. Для работы с VKS через сайт используется пользовательская сессия, этот ключ не нужен. См. [VKS в личном кабинете](/ru/guides/vks).

## Обращение с ключом 

Считайте ключ непрозрачным секретом. Префикс обозначает его назначение; передавайте полное значение без изменений. Не вычисляйте и не проверяйте его содержимое самостоятельно.

Сохраните секрет сразу
Сохраните ключ из ответа создания в менеджере секретов. Контракты создания ключа позволяют вызывающему с нужным доступом повторить тот же запрос с прежним `Idempotency-Key` и получить секрет в течение 60 секунд после успешного создания, при текущем доступе и допустимом состоянии ключа. Повторы не продлевают окно и не восстанавливают отозванный или удалённый ключ. Поздние чтения возвращают только маску и метаданные. Подробнее о сроках и ограничениях: [Идемпотентность](/ru/apis/idempotency#replay). Если окно истекло, сначала найдите созданный ключ и при необходимости отзовите его; новый ключ создавайте отдельным осознанным действием.

## Передача ключа 

Передавайте ключ в заголовке `X-Api-Key` в каждом аутентифицированном API-запросе - никогда в строке запроса или пути URL, где он попадает в логи, прокси и историю браузера.

Откройте страницу нужной операции и укажите ключ в форме авторизации. Например, [список сетей](/ru/apis/platform/api/blockchain/list-blockchains) содержит примеры запросов на разных языках.

## Права и области 

Ключ никогда не несёт безграничный доступ. При создании вы выдаёте ему фиксированный набор прав - строки вида `api:address:read` - и любой вызов вне этого набора отклоняется с `403`. Расширить права позже нельзя; чтобы изменить, отзовите ключ и выпустите новый.

Модель прав, полный каталог по сервисам и то, как роли отображаются в них, - в [справочнике прав](/ru/apis/permissions).

## Когда аутентификация не проходит 

Ошибки аутентификации возвращаются в формате `application/problem+json`:

| Статус | Что значит | Как исправить |
|  --- | --- | --- |
| [`401`](/ru/apis/errors#unauthorized) | Ключ отсутствует, повреждён или отозван | Передайте корректный ключ в `X-Api-Key` |
| [`403`](/ru/apis/errors#forbidden) | Ключ верный, но не хватает нужного права | Выпустите замену с нужными [правами](/ru/apis/permissions) |


## Лучшие практики 

Ключи - только на сервере

Никогда не отдавайте ключ в браузер или мобильное приложение. Плательщики используют неаутентифицированную публичную страницу счёта.

Минимум привилегий

Для чтения списка адресов нужен `api:address:read`, а не все права. Ограничивайте каждый ключ той единственной задачей, которую он решает.

Свой ключ на окружение

Разделяйте разработку, staging и продакшен - отзыв одного не затрагивает остальные.

Ротация при смене команды

Когда человек с доступом к ключу уходит, ротируйте - выпустите новый ключ, переключите трафик, отзовите старый.

## Ротация ключа 

Любой ключ - API, RPC или управляющий - можно ротировать без простоя:

1. Создайте новый ключ с теми же правами.
2. Переключите приложение на новый ключ.
3. Убедитесь, что новый ключ работает в production.
4. Отзовите старый ключ.


## Подписи вебхуков 

Доставки вебхуков подписываются по HMAC-SHA256, чтобы вы могли убедиться, что они пришли от Vilna. Заголовки подписи, жизненный цикл секрета подписи и код проверки описаны в [справочнике по вебхукам](/ru/apis/platform/webhooks#verify).