API Keys

API Keys позволяют авторизоваться в ONREZA API для автоматизации и интеграций. Ключи привязаны к конкретному workspace и имеют собственный набор разрешений (permissions), который определяет, какие операции ими можно выполнять.

Workspace-scoped Keys

API Keys в ONREZA привязаны к конкретному workspace, а не к пользовательскому аккаунту. Это значит:

Ключ даёт доступ только к ресурсам одного workspace
Ключи хранятся в контексте workspace и доступны через Team Settings
При смене workspace вам потребуется другой ключ или указать workspace через заголовок

Формат ключа

API Keys ONREZA имеют формат:

nrz_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Префикс nrz_ для идентификации ключей ONREZA
32 символа после префикса (буквы и цифры)

Пример:

nrz_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Permissions и пресеты

Каждый ключ имеет набор permissions — точечных разрешений на типы операций (чтение деплоев, запись доменов и т.д.). Фактические права, с которыми выполнится запрос, — это пересечение прав роли владельца ключа и permissions самого ключа. Ключ не может делать больше, чем разрешает роль его автора, и не может делать больше, чем позволяют его permissions.

Пресеты

Для большинства сценариев хватает одного из трёх пресетов:

Пресет	Что разрешено	Когда использовать
Чтение	Чтение деплоев, проектов, переменных окружения, доменов, команды и биллинга	Мониторинг, дашборды, read-only интеграции
Deploy	Всё из «Чтения» + создание деплоев и редактирование переменных окружения	CI/CD, автодеплой из GitHub Actions (рекомендуется по умолчанию)
Полный	Все доступные ключу permissions	Универсальная автоматизация, миграции

При создании ключа в UI по умолчанию предлагается пресет Deploy — он покрывает стандартный CI/CD-сценарий и не даёт лишних прав.

Свой набор permissions

Если ни один пресет не подходит, выберите Свой набор и отметьте только нужные разрешения. Они сгруппированы по ресурсам:

Ресурс	Permission	Действия
Deployments	`deployments.read`	Просмотр деплоев, логов, статусов
Deployments	`deployments.write`	Создание деплоев, откат, отмена
Projects	`projects.read`	Просмотр проектов и настроек
Projects	`projects.write`	Редактирование настроек, создание проектов
Projects	`projects.admin`	Удаление и переименование проектов
Env Vars	`env.read`	Просмотр названий переменных (без значений секретов)
Env Vars	`env.write`	Создание, редактирование, удаление переменных
Domains	`domains.read`	Просмотр доменов и их статусов
Domains	`domains.write`	Добавление, удаление, верификация доменов
Team	`team.read`	Просмотр участников и их ролей
Billing	`billing.read`	Просмотр подписки, инвойсов и биллинг-профиля

Что недоступно API Keys

Часть операций в принципе нельзя выполнять API ключом — даже если у вас роль OWNER:

Изменение состава команды и ролей участников (team.write)
Управление подпиской, платёжными методами и биллинг-реквизитами (billing.write)
Передача владения workspace и удаление workspace (workspace.admin)

Эти действия требуют интерактивного входа как пользователь (session + 2FA при необходимости). Такое ограничение защищает от ситуации, когда утечка API-ключа с полными правами приводит к потере контроля над workspace.

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

Откройте настройки

Перейдите в Team Settings → API Keys
Нажмите “Create Key”

Заполните форму

Поле	Описание	Обязательно
Name	Название для идентификации (например, “GitHub Actions”)	Да
Permissions	Один из пресетов (Чтение / Deploy / Полный) или свой набор	Да
Expiration	Срок действия ключа	Нет

Скопируйте ключ

Ключ показывается только один раз. Сохраните его в безопасном месте.

Роли и доступ к управлению

Сам факт доступа к созданию и управлению API Keys определяется ролью в workspace:

Роль	Доступ к API Keys
OWNER	Видит и управляет всеми ключами workspace
ADMIN	Видит и управляет всеми ключами workspace
MEMBER	Видит и управляет только своими ключами
BILLING	Нет доступа к API Keys

Permissions ключа, созданного участником, всё равно ограничены его ролью: MEMBER не сможет выпустить ключ с правами, которых у него нет.

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

Вы можете выбрать срок действия от 1 до 365 дней:

Рекомендация	Срок	Использование
Рекомендуется	30 дней	Стандартный выбор для CI/CD
Рекомендуется	90 дней	Долгосрочные интеграции
Осторожно	365 дней	Максимальный срок
Осторожно	Без срока	Не рекомендуется по соображениям безопасности

Использование

Environment Variable

Установите токен как переменную окружения для CI/CD и автоматизации:

export NRZ_TOKEN="nrz_YOUR_KEY"

Пример: Деплой через CLI

export NRZ_TOKEN="nrz_YOUR_KEY"
nrz deploy

Rate Limiting

Запросы с аутентификацией по API key ограничены 5000 запросами в час на ключ (с допустимым кратковременным всплеском).

При превышении лимита возвращается ошибка 429 Too Many Requests.

Управление ключами

Просмотр списка

Team Settings → API Keys

Для каждого ключа видно:

Название
Начало ключа (первые символы)
Набор permissions (как badge пресета «Чтение» / «Deploy» / «Полный» или «Свой (N)»)
Дата создания и дата истечения
Последнее использование
Создатель ключа

Строку можно раскрыть, чтобы увидеть точный список permissions этого ключа.

Редактирование

У ключа можно менять name, enabled-статус и набор permissions без пересоздания. Старое значение ключа при этом не меняется.

Найдите ключ в списке
Нажмите Edit
Обновите название или permissions
Нажмите Save

Изменения применяются сразу — кэш авторизации сбрасывается перед обновлением, поэтому у ключа не остаётся окна «со старыми правами».

Удаление

Найдите ключ в списке
Нажмите удалить (корзина)
Подтвердите

Ключ перестаёт работать сразу после удаления.

Bulk операции

Выберите несколько ключей и удалите их одним действием (доступно OWNER и ADMIN).

Безопасность

Best Practices

Выбирайте минимальный пресет — для большинства CI/CD достаточно Deploy, не используйте Полный без необходимости
Ограничивайте срок — используйте expiration
Ротируйте регулярно — создавайте новые ключи периодически
Один ключ — одна цель — разные ключи для разных систем
Мониторьте использование — проверяйте “Last used”
Храните в секретах — используйте GitHub Secrets, GitLab Variables и т.д.

Если ключ скомпрометирован

Немедленно удалите ключ
Создайте новый (с минимально необходимым пресетом)
Обновите во всех системах
Проверьте историю активности

Интеграция с CI/CD

GitHub Actions

name: Deploy to ONREZA

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup ONREZA CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/ONREZA/nrz-cli/main/install.sh | bash
      - name: Deploy
        env:
          NRZ_TOKEN: ${{ secrets.NRZ_TOKEN }}
        run: |
          nrz deploy

GitLab CI

deploy:
  stage: deploy
  variables:
    NRZ_TOKEN: $NRZ_TOKEN
  before_script:
    - curl -fsSL https://raw.githubusercontent.com/ONREZA/nrz-cli/main/install.sh | bash
  script:
    - nrz deploy
  only:
    - main

Troubleshooting

“Unauthorized”

Проверьте что ключ скопирован полностью
Проверьте формат: Bearer KEY (для HTTP) или просто KEY (для CLI)
Проверьте что ключ не истёк и не отключён
Проверьте что ключ не удалён
Убедитесь что указан правильный workspace

“Forbidden”

Проверьте permissions ключа — у него может не быть права на этот ресурс (см. badge и раскрытый список в таблице)
Проверьте роль владельца в workspace — ключ не может превысить её
Убедитесь, что нужное действие в принципе доступно API Keys (см. Что недоступно API Keys)

“Workspace not found”

Проверьте правильность workspace slug
Убедитесь что ключ принадлежит указанному workspace
Используйте CLI для автоматического определения workspace из токена

Ключ не работает

Создайте новый ключ
Проверьте что нет пробелов/переносов
Убедитесь что используете правильный формат для выбранного инструмента

См. также

Deploy Hooks — триггеры без API
Управление участниками — роли в workspace
Настройки — обзор настроек