Перейти к основному содержанию
Каждую долгоживущую учётку следует заменять по расписанию и немедленно при любом намёке на раскрытие. Безопасный способ ротировать учётки API-ключей — никогда не мутировать живой ключ на месте, а выпустить свежий, перевести на него трафик и вывести старый из эксплуатации, как только от него ничего не зависит. Сделанная в этом порядке ротация никогда не оставляет момента без рабочего ключа. Эта страница — пошаговый плейбук. О более широком жизненном цикле ключа (создать / отключить / удалить) см. Управление ключами; о каждом поле, которое несёт ключ, см. Объект токена.
Все консольные действия здесь живут на экране Keys (/console/token) и выполняются на вашем сессионном / access-токене, а не на ключе ретрансляции. Создание, редактирование, отключение или удаление ключа требует роли Developer или выше. Только вызовы инференса /v1/* используют ключ ретрансляции sk-orca-….

​
1. Зачем ротировать и почему никогда на месте

Ключ в OrcaRouter — это неизменяемая идентичность, а не просто строка — он несёт собственный список разрешённых моделей, список разрешённых IP, лимит расходов, срок действия и привязки политик. Вы не можете изменить секретный материал существующего ключа; учётка и ограничения выпускаются вместе при создании. Так что «ротация» означает выпуск преемника и миграцию на него. Делайте это:
  • по фиксированному ритму для любой production-учётки (поквартально — распространённый базис);
  • в момент, когда ключ заподозрен в утечке — хотя для подтверждённой утечки сначала отрежьте его, а ротируйте вторым (см. Реагирование на утечку ключа);
  • всякий раз, когда меняется владелец ключа (сотрудник, вендорская интеграция, выведенный из эксплуатации агент).
Открытый текст (sk-orca-…) показывается один раз, при создании — скопируйте его тогда. После этого консоль показывает только маскированную форму вроде orca-7Bf****wxyz. Developer+ может позже повторно раскрыть открытый текст обычного ключа, но ключ с областью шлюза (is_firewall_gateway) требует Admin, чтобы снова прочитать его открытый текст — так что относитесь к первому раскрытию ключа шлюза как к вашей единственной надёжной копии.

​
2. Последовательность ротации API-ключа

Весь смысл в чистом перекрытии: новый ключ работает, прежде чем старый останавливается. Четыре шага.
1

Создайте ключ-преемник

Выпустите новый ключ с той же областью, что и у заменяемого — те же model_limits, allow_ips, credit_limit_usd, expired_time и те же guardrail_id / firewall_policy_id. Скопируйте открытый текст немедленно. Ротация — идеальный момент, чтобы ужесточить область тоже: уберите модель, которую агент больше не использует, или сузьте список разрешённых IP.
2

Мигрируйте трафик

Разверните новый sk-orca-… на каждого вызывающего — конфиг, менеджер секретов, переменную CI, рантайм агента. Раскатайте его так же, как вы отгружаете любое изменение секрета. Оба ключа живы на этом этапе, так что деплои можно делать вразнобой без простоя.
3

Убедитесь, что новый ключ несёт нагрузку

Подтвердите, что преемник действительно обслуживает трафик, прежде чем трогать старый. Следите, как used_quota нового ключа растёт, пока у старого выравнивается — использование на ключ это ваш сигнал переключения.
4

Выведите старый ключ из эксплуатации

Как только старый ключ не показывает трафика, сначала отключите его (обратимо) и следите за отставшими, затем удалите его навсегда. Отключение — это пауза; удаление — точка невозврата.
Задайте метку environment на каждом ключе — переиспользуйте её для старого и нового ключа или меняйте (prod → prod-2026q2) — так что преемник и предшественник помечены различимо, пока оба живы во время окна перекрытия.

​
3. Конкретная ротация через REST

Всё ниже — консольное действие; эти маршруты управления выполняются под вашей сессией (UserAuth), а не ключом ретрансляции. Предположим, вы заменяете ключ для запланированного агента суммаризации. Создайте преемника с той же областью: 
# Console session token — NOT an sk-orca-… relay key
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
Ответ возвращает открытый текст один раз ("data": "sk-orca-…"). Скопируйте его, разверните на суммаризатор и подтвердите, что новый ключ обслуживает, прежде чем двигаться дальше. Когда старый ключ (id 481) не показывает трафика, отключите, затем удалите его: 
# Pause first (reversible) — set the old key's status to Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Once you're sure nothing depends on it — revoke for good
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
Статус ключа — это один из Enabled (1), Disabled (2), Expired (3) или Exhausted (4). Отключение ставит его в Disabled; каждый запрос, который делает ключ, затем отклоняется, при этом его конфигурация, привязки и история остаются нетронутыми. Удаление необратимо — учётка больше никогда не сможет авторизовать запрос, а удалённый ключ невосстановим.
Вы можете сделать всё это без API — на экране Keys есть New key, тумблер Disabled на каждый ключ и Delete (одиночный или пакетный). REST-форма выше — для скриптинга запланированных ротаций.

​
4. Ротация ключей, привязанных к политикам, и ключей шлюза

Привязки guardrail и firewall ключа живут на ключе, так что преемник должен нести те же guardrail_id и firewall_policy_id, чтобы применять ту же позицию. Две вещи, которые надо знать:
Guardrails и политики firewall — это именованные ресурсы в рамках рабочего пространства, общие между ключами. Ротация ключа не трогает саму политику; вы просто перенаправляете свежий ключ на существующий guardrail_id / firewall_policy_id. Политика продолжает управлять трафиком без перерыва.
Ключ с установленным is_firewall_gateway приводит в действие маршруты шлюза Firewall (/api/v1/firewall/*). Выпуск такого и повторное раскрытие его открытого текста оба требуют Admin. Поскольку вы не можете мимоходом перечитать его секрет, захватите открытый текст нового ключа шлюза при создании и сохраните его в менеджере секретов, прежде чем переключаться.
Не переиспользуйте один ключ — шлюзовой или нет — на много агентов и не «ротируйте» редактированием лимитов. Один ключ на агента держит каждую ротацию изолированной, а радиус поражения малым. См. Чек-лист минимальных полномочий.

​
5. Экстренная ротация (подозрение на утечку)

Если вы думаете, что ключ раскрыт, порядок переворачивается: сначала остановите кровотечение, мигрируйте вторым.
  1. Отключите подозрительный ключ сразу, чтобы он не мог ничего авторизовать, пока вы расследуете — или удалите его сразу, если утечка подтверждена.
  2. Выпустите преемника и раскатайте его как в §2.
  3. Просмотрите, что делал утёкший ключ, прежде чем вы его отрезали: отфильтруйте логи запросов по этому ключу (токену), чтобы ограничить радиус поражения.
Полный runbook инцидента — на Реагировании на утечку ключа.
Короткий expired_time — это страховка ротации: истекающий ключ выводит себя из эксплуатации, даже если вы забудете о ручной ротации, ограничивая, как долго любая отдельная учётка может вообще быть в злоупотреблении.

​
6. Дальнейшие шаги

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

Жизненный цикл создать / отключить / отозвать, на котором строятся эти шаги.

Привязка политик к ключу

Перенесите тот же guardrail и политику firewall на преемника.

Истекающие ключи

Задайте срок действия, чтобы ключи ротировали себя по дедлайну.

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

Экстренный путь, когда учётка раскрыта.
Ротация — это просто дисциплинированное перекрытие: преемник, который работает, прежде чем предшественник останавливается. Держите каждый ключ узко ограниченным, и передача остаётся скучной — а это ровно то, что вам нужно от ротации учётки.