Это руководство объясняет, как организованы рабочие пространства, проекты, участники и API-ключи в Vilna. Детали эндпоинтов в Справочнике API. Роли и разрешения описаны в Авторизации.
Всё в Vilna организовано внутри рабочих пространств:
- Рабочее пространство - единица верхнего уровня. Каждый пользователь может создать до 5 рабочих пространств.
- Проекты находятся внутри рабочего пространства и обеспечивают изоляцию данных - у каждого проекта свои мониторируемые адреса, транзакции и API-ключи.
- Участники - пользователи с доступом к рабочему пространству. Добавляются через приглашения.
- API-ключи привязаны к проекту. RPC-ключи и management-ключи привязаны к рабочему пространству.
Vilna использует три типа API-ключей, каждый с уникальным префиксом и областью действия:
| Тип | Префикс | Область | Что открывает доступ |
|---|---|---|---|
| API-ключ | vilna_api_ | Проект | Platform API - адреса, транзакции, балансы, события, счета |
| RPC-ключ | vilna_rpc_ | Рабочее пространство | Blockchain RPC - JSON-RPC и gRPC доступ к нодам |
| Management-ключ | vilna_mgt_ | Рабочее пространство | Management API - рабочие пространства, участники, проекты, ключи |
Каждый ключ несёт встроенный набор разрешений. При создании ключа вы указываете, какие разрешения ему предоставить. Ключ может выполнять только действия в рамках предоставленных разрешений.
Значение ключа возвращается только один раз при создании. Его невозможно получить повторно. Сохраните его в менеджере секретов или переменной окружения сразу.
Новые участники присоединяются к рабочему пространству через email-приглашения:
- Владелец или администратор создаёт приглашение на email с ролью (
adminилиmember). - Приглашённый получает приглашение и может принять или отклонить.
- При принятии пользователь становится участником с назначенной ролью.
- Ожидающие приглашения могут быть отозваны любым владельцем или администратором.
| Статус | Значение |
|---|---|
pending | Приглашение отправлено, ожидает ответа |
accepted | Пользователь принял и стал участником |
declined | Пользователь отклонил приглашение |
revoked | Владелец или администратор отменил приглашение |
Роль владельца назначается при создании рабочего пространства и не может быть изменена через приглашения. Приглашать можно только с ролью admin или member.
Для ротации API-ключа без простоя:
- Создайте новый ключ с теми же разрешениями.
- Обновите приложение для использования нового ключа.
- Убедитесь, что новый ключ работает в production.
- Отзовите старый ключ.
Тот же процесс применим для RPC-ключей и management-ключей.
- Создайте проект в рабочем пространстве (через дашборд или API).
- Создайте API-ключ для проекта с необходимыми разрешениями.
- Используйте API-ключ в заголовке
X-Api-Keyдля доступа к Platform API.
- Отправьте приглашение на email пользователя.
- После принятия назначьте участника на конкретные проекты, если его роль
member(администраторы видят все проекты автоматически). - Участник может работать с рабочим пространством через дашборд.
Если ваша платформа обслуживает нескольких клиентов, настройку для каждого можно автоматизировать:
- Создайте проект для каждого клиента.
- Программно сгенерируйте API-ключи для каждого проекта.
- Безопасно передайте ключи интеграциям каждого клиента.
Этот паттерн используется биржами, платёжными системами и другими платформами, управляющими несколькими изолированными средами. Детали эндпоинтов в Справочнике API.