Przejdź do głównej treści
Każde długożyciowe poświadczenie powinno być wymieniane według harmonogramu i natychmiast na każdy ślad ekspozycji. Bezpieczny sposób, by rotować klucz api, to nigdy nie mutować żywego klucza w miejscu — to wybić świeży, przenieść na niego ruch i wycofać stary, gdy nic od niego nie zależy. Zrobione w tej kolejności, nigdy nie ma momentu bez działającego klucza. Ta strona to podręcznik krok po kroku. Po szerszy cykl życia klucza (tworzenie / wyłączanie / usuwanie) zobacz Zarządzanie kluczami; po każde pole, które niesie klucz, zobacz Obiekt tokenu.
Wszystkie akcje konsolowe tutaj żyją na ekranie Klucze (/console/token) i działają na twoim tokenie sesji / dostępu — nie na kluczu relay. Tworzenie, edycja, wyłączanie lub usuwanie klucza wymaga roli Developer lub wyższej. Tylko wywołania inferencji /v1/* używają klucza relay sk-orca-….

​
1. Po co rotować i dlaczego nigdy w miejscu

Klucz na OrcaRouter to niemutowalna tożsamość, nie tylko ciąg — niesie własną listę dozwolonych modeli, listę dozwolonych IP, limit wydatków, wygaśnięcie i załączniki polityk. Nie możesz zmienić materiału sekretu istniejącego klucza; poświadczenie i ograniczenia są wydawane razem przy tworzeniu. Więc „rotowanie” oznacza wydanie następcy i migrację na niego. Rób to:
  • w stałym rytmie dla każdego produkcyjnego poświadczenia (kwartalnie to częsta baza);
  • w chwili, gdy klucz jest podejrzany o wyciek — choć dla potwierdzonego wycieku najpierw go odetnij, a rotuj w drugiej kolejności (zobacz Reakcję na wyciekły klucz);
  • zawsze, gdy zmienia się właściciel klucza (pracownik, integracja dostawcy, wycofany agent).
Plaintext (sk-orca-…) jest pokazywany raz, przy tworzeniu — skopiuj go wtedy. Potem konsola pokazuje tylko formę zamaskowaną jak orca-7Bf****wxyz. Developer+ może później ponownie ujawnić plaintext zwykłego klucza, ale klucz w zakresie gateway (is_firewall_gateway) wymaga Admin, by odczytać jego plaintext znów — więc traktuj pierwsze ujawnienie klucza gateway jako swoją jedyną niezawodną kopię.

​
2. Sekwencja rotacji klucza api

Cały sens to czyste nakładanie się: nowy klucz działa, zanim stary się zatrzyma. Cztery kroki.
1

Utwórz klucz następcy

Wybij nowy klucz z tym samym zakresem co ten, który zastępujesz — te same model_limits, allow_ips, credit_limit_usd, expired_time oraz te same guardrail_id / firewall_policy_id. Skopiuj plaintext natychmiast. Rotacja to idealny moment, by też zacieśnić zakres: porzuć model, którego agent już nie używa, lub zawęź listę dozwolonych IP.
2

Zmigruj ruch

Wdróż nowy sk-orca-… do każdego wywołującego — config, menedżer sekretów, zmienna CI, runtime agenta. Wprowadź go tak, jak dostarczasz każdą zmianę sekretu. Oba klucze są żywe na tym etapie, więc wdrożenia mogą być rozłożone bez awarii.
3

Zweryfikuj, że nowy klucz dźwiga obciążenie

Potwierdź, że następca faktycznie obsługuje ruch, zanim dotkniesz starego. Obserwuj, jak used_quota nowego klucza rośnie, a starego klucza spłaszcza się — użycie per klucz to twój sygnał przełączenia.
4

Wycofaj stary klucz

Gdy stary klucz nie pokazuje ruchu, najpierw go wyłącz (odwracalne) i wypatruj maruderów, potem usuń na dobre. Wyłączenie to pauza; usunięcie to punkt bez powrotu.
Ustaw etykietę environment na każdym kluczu — użyj jej ponownie na starym i nowym kluczu lub podbij ją (prod → prod-2026q2) — tak by następca i poprzednik były odrębnie oznaczone, gdy oba są żywe w oknie nakładania.

​
3. Konkretna rotacja, przez REST

Wszystko poniżej to akcja konsolowa — te trasy zarządzania działają pod twoją sesją (UserAuth), nie kluczem relay. Załóżmy, że zastępujesz klucz zaplanowanego agenta do streszczania. Utwórz następcę z tym samym zakresem: 
# Token sesji konsoli — NIE klucz relay sk-orca-…
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
  }'
Odpowiedź zwraca plaintext raz ("data": "sk-orca-…"). Skopiuj go, wdróż do streszczacza i potwierdź, że nowy klucz obsługuje, zanim ruszysz dalej. Gdy stary klucz (id 481) nie pokazuje ruchu, wyłącz, a potem usuń go: 
# Najpierw pauza (odwracalne) — ustaw status starego klucza na 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}'

# Gdy masz pewność, że nic od niego nie zależy — unieważnij na dobre
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
Status klucza to jeden z Enabled (1), Disabled (2), Expired (3) lub Exhausted (4). Wyłączenie ustawia go na Disabled; każde żądanie, które klucz wykonuje, jest wtedy odrzucane, podczas gdy jego konfiguracja, załączniki i historia pozostają nienaruszone. Usunięcie jest trwałe — poświadczenie nigdy więcej nie autoryzuje żądania, a usuniętego klucza nie da się odzyskać.
Możesz zrobić to wszystko bez API — ekran Klucze ma Nowy klucz, przełącznik Disabled per klucz oraz Usuń (pojedynczo lub wsadowo). Forma REST powyżej jest do skryptowania zaplanowanych rotacji.

​
4. Rotacja kluczy powiązanych z polityką i kluczy gateway

Załączniki guardrail i firewall klucza żyją na kluczu, więc następca musi nieść te same guardrail_id i firewall_policy_id, by egzekwować tę samą postawę. Dwie rzeczy do wiedzy:
Guardrails i polityki firewalla to nazwane zasoby w zakresie przestrzeni roboczej, współdzielone między kluczami. Rotacja klucza nie dotyka samej polityki; jedynie ponownie kierujesz świeży klucz na istniejący guardrail_id / firewall_policy_id. Polityka dalej rządzi ruchem nieprzerwanie.
Klucz z ustawionym is_firewall_gateway napędza trasy bramy Firewall (/api/v1/firewall/*). Wybicie takiego oraz ponowne ujawnienie jego plaintextu oba wymagają Admin. Ponieważ nie możesz swobodnie ponownie odczytać jego sekretu, przechwyć plaintext nowego klucza gateway przy tworzeniu i zapisz go w menedżerze sekretów, zanim przełączysz.
Nie używaj ponownie pojedynczego klucza — gateway czy innego — w wielu agentach i „rotuj” przez edycję limitów. Jeden klucz na agenta utrzymuje każdą rotację izolowaną, a promień rażenia mały. Zobacz Listę kontrolną minimalnych uprawnień.

​
5. Rotacja awaryjna (podejrzewany wyciek)

Jeśli sądzisz, że klucz jest ujawniony, kolejność się odwraca: najpierw zatamuj krwawienie, migruj w drugiej kolejności.
  1. Wyłącz podejrzany klucz od razu, tak by nie mógł niczego autoryzować, gdy badasz — albo usuń go wprost, jeśli wyciek jest potwierdzony.
  2. Wybij następcę i wprowadź go jak w §2.
  3. Przejrzyj, co wyciekły klucz robił, zanim go odetniesz: przefiltruj logi żądań po tym kluczu (tokenie), by ograniczyć promień rażenia.
Pełny runbook incydentu jest w Reakcji na wyciekły klucz.
Krótki expired_time to ubezpieczenie rotacji: wygasający klucz sam się wycofuje, nawet jeśli zapomnisz ręcznej rotacji, ograniczając, jak długo jakiekolwiek pojedyncze poświadczenie może być nadużywane.

​
6. Kolejne kroki

Zarządzanie kluczami

Cykl życia tworzenie / wyłączanie / unieważnianie, na którym te kroki bazują.

Powiązanie polityk z kluczem

Przenieś tę samą politykę guardrail i firewall na następcę.

Klucze wygasające

Ustaw wygaśnięcie, tak by klucze rotowały się same na termin.

Reakcja na wyciekły klucz

Ścieżka awaryjna, gdy poświadczenie jest ujawnione.
Rotacja to po prostu zdyscyplinowane nakładanie się: następca, który działa, zanim poprzednik się zatrzyma. Trzymaj każdy klucz wąsko ograniczonym, a przekazanie pozostanie nudne — co jest dokładnie tym, czego chcesz od rotacji poświadczenia.