API Keys

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

Workspace-scoped Keys

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

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

Заметка

Для простых сценариев (деплой по событию) лучше используйте Deploy Hooks — они не требуют полного API доступа и проще в настройке.

Формат ключа

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

nrz_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

Пример:

nrz_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

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

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

   Перейдите в Team Settings → API Keys

2. Нажмите “Create Key”

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

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

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

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

Осторожно

Ключ показывается только при создании. Если потеряете — нужно создать новый.

Права доступа

Доступ к API Keys и их управление различается в зависимости от роли в workspace:

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

Совет

MEMBER может создавать, просматривать и удалять только те ключи, которые создал сам. OWNER и ADMIN имеют полный доступ ко всем ключам workspace.

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

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

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

Совет

Рекомендуется использовать ключи с ограниченным сроком (30-90 дней) и регулярно их ротировать.

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

Environment Variable

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

export NRZ_TOKEN="nrz_YOUR_KEY"

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

export NRZ_TOKEN="nrz_YOUR_KEY"
nrz deploy

Заметка

Переменная NRZ_TOKEN используется CLI для авторизации API-запросов.

Rate Limiting

API Keys имеют ограничение 100 запросов в час.

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

Заметка

Для Deploy Hooks rate limiting отдельный и более мягкий.

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

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

Team Settings → API Keys

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

• Название
• Начало ключа (первые символы)
• Дата создания
• Дата истечения
• Последнее использование
• Создатель ключа

Заметка

MEMBER видит только свои ключи. OWNER и ADMIN видят все ключи workspace.

Удаление ключа

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

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

Bulk операции

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

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

Best Practices

1. Ограничивайте срок — используйте expiration
2. Ротируйте регулярно — создавайте новые ключи периодически
3. Один ключ — одна цель — разные ключи для разных систем
4. Мониторьте использование — проверяйте “Last used”
5. Храните в секретах — используйте GitHub Secrets, GitLab Variables и т.д.

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

1. Немедленно удалите ключ
2. Создайте новый
3. Обновите во всех системах
4. Проверьте историю активности

Интеграция с 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

Совет

Для простого триггера деплоя при пуше удобнее использовать Deploy Hooks — они не требуют хранения ключа.

Кэширование

Для оптимизации производительности API Keys используют L2 Cache с TTL 30 секунд. Это означает:

• Проверка ключа может кэшироваться на 30 секунд
• После удаления ключа он может продолжать работать до 30 секунд
• После создания ключа может пройти до 30 секунд перед активацией

Troubleshooting

”Unauthorized”

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

”Forbidden”

1. Проверьте права на ресурс
2. Убедитесь что у ключа есть доступ к указанному workspace
3. Проверьте роль в workspace (MEMBER видит только свои ключи)

“Workspace not found”

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

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

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

См. также

• Deploy Hooks — триггеры без API
• Team Settings — управление командой
• Настройки — обзор настроек