Przejdź do głównej treści
Aby uruchamiać wywołania narzędzi przez firewall agentowy spoza relay modelu — twoja własna pętla agenta wołająca hook evaluate albo klient MCP łączący się z bramą MCP — uwierzytelniasz się dedykowanym kluczem w zakresie firewall-gateway, nie zwykłym kluczem relay sk-orca-…. Zwykły klucz dostaje 403 na uwierzytelnianych tokenem trasach bramy firewalla (callback zatwierdzeń to jeden wyjątek — jest podpisany HMAC, nie bramkowany tokenem). Ta strona omawia, czym jest klucz API gateway firewalla, jak wybić jeden i dlaczego zakres jest bramkowany do Admin+. Dla samego silnika zobacz Przegląd Firewall i głęboką referencję w Firewall.

​
1. Czym jest klucz API gateway firewalla

Każdy token (klucz API) w twojej przestrzeni roboczej niesie flagę is_firewall_gateway. Gdy jest true, klucz może sięgnąć do powierzchni bramy firewalla:
TrasaCo robi
POST /api/v1/firewall/evaluateWerdykt przed-dyspozycją dla jednego wywołania narzędzia.
POST /api/v1/firewall/evaluate_planSprawdzenie przed-wykonaniem dla wielokrokowego planu.
ANY /api/v1/firewall/mcpUjednolicony endpoint bramy MCP.
GET /api/v1/firewall/mcp_serversWymień zarejestrowane serwery MCP przestrzeni roboczej (zwraca odszyfrowane auth nadrzędne).
GET /api/v1/firewall/approvals/:idOdpytaj stan zatwierdzenia wstrzymanego wywołania.
Klucz z is_firewall_gateway = false (domyślnie) to zwykły klucz relay — obsługuje ruch modelu /v1/* i, jeśli przypiąłeś politykę przez firewall_policy_id, jego wywołania narzędzi są zarządzane inline. Ale nie może wywoływać tras bramy powyżej.
Dwa różne klucze, dwie różne prace. Twój klucz relay (z przypiętym firewall_policy_id) to to, czego twój agent używa, by rozmawiać z modelami — firewall zarządza jego wywołaniami narzędzi automatycznie. Klucz gateway firewalla to to, czego środowisko uruchomieniowe twojego agenta używa, by zapytać firewall o werdykt bezpośrednio lub by proksować tools/call MCP przez bramę. Większość przestrzeni roboczych potrzebuje klucza gateway dopiero, gdy adoptuje hook evaluate lub bramę MCP.

​
2. Dlaczego zwykły klucz dostaje 403

Zakres gateway odblokowuje dwie wrażliwe na sekrety zdolności, więc jest celowo odgrodzony od zwykłych kluczy:
  • /evaluate przyjmuje dostarczone przez wywołującego request_id, które wpływa do zdarzenia firewalla i rekordów zatwierdzeń. Możliwość fałszowania zdarzeń audytu lub po cichu sondowania wyników polityki przez dowolny klucz modelu podważyłaby ślad.
  • /mcp_servers zwraca odszyfrowane poświadczenia nadrzędne, więc proksy SDK może dyspozytować do twoich zarejestrowanych serwerów MCP. To odczyt poświadczeń, nie wywołanie modelu.
Z tego powodu handler sprawdza flagę is_firewall_gateway prezentowanego tokenu i zwraca HTTP 403, gdy jej brak: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Nie używaj ponownie klucza relay o wysokim ruchu jako klucza gateway i nie używaj ponownie klucza gateway dla ruchu relay. Trzymaj klucz płaszczyzny akcji osobno, by jego promień rażenia i rotacja były niezależne od twoich kluczy modelu.

​
3. Wybij jeden — bramkowany rolą do Admin+

Ustawienie is_firewall_gateway = true wymaga Admina przestrzeni roboczej lub wyżej. Developer może tworzyć i edytować zwykłe klucze, ale nie może wybić klucza w zakresie gateway — flaga to sprawa zarządzania sekretami, więc siedzi ponad zwykłą rolą zapisu tokenu. Konfigurujesz klucze w konsoli, pod kluczami API swojej przestrzeni roboczej. Aby wybić klucz gateway:
1

Otwórz klucze API jako Admin

Zaloguj się jako Admin przestrzeni roboczej (lub wyżej) i otwórz stronę kluczy API w konsoli.
2

Utwórz klucz z zakresem gateway

Utwórz nowy klucz i włącz jego zakres firewall gateway (is_firewall_gateway). Sesja roli Developer nie zobaczy, by zakres wszedł w życie — serwer trzyma flagę false dla nie-adminów.
3

Skopiuj klucz raz

Skopiuj pełną wartość klucza przy tworzeniu. Potem konsola maskuje go przy wyświetlaniu, a odczyt jawnego tekstu klucza gateway z powrotem jest sam w sobie Admin+ — nie-admini dostają wiersze gateway pominięte z odpowiedzi „pobierz moje klucze”.
Obniżanie flagi jest bardziej permisywne niż jej podnoszenie: czyszczenie is_firewall_gateway (degradacja klucza gateway z powrotem do zwykłego klucza) jest otwarte dla każdej roli, która może edytować klucz. Tylko podnoszenie go do true jest Admin+.

​
Bramy ról w skrócie

AkcjaRola
Utwórz/edytuj zwykły kluczDeveloper+
Ustaw is_firewall_gateway = trueAdmin+
Odczytaj jawny tekst klucza gateway z powrotemAdmin+
Wyczyść is_firewall_gateway (degraduj)dowolny edytor klucza

​
4. Jeden konkretny przykład

Uruchamiasz pętlę agenta i chcesz sprawdzić wywołanie narzędzia przed jego dyspozycją. Jako Admin wybij klucz gateway w konsoli, potem wywołaj hook evaluate ze swojego środowiska uruchomieniowego tym kluczem: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
Firewall rozwiązuje aktywną politykę twojej przestrzeni roboczej i zwraca werdykt — allow, audit, deny, sanitize, pending_approval lub rozwiązanie cap_cost. Twój agent na nim działa: dyspozytuj na allow, pomiń na deny, odpytuj id zatwierdzenia na pending_approval. Ten sam klucz gateway uwierzytelnia odpytywanie zatwierdzeń i trasy MCP.
Kierujesz klienta MCP (Claude Desktop, Cursor, framework agentowy) na https://api.orcarouter.ai/api/v1/firewall/mcp? Użyj klucza gateway jako jego tokenu bearer. Każde tools/call jest wtedy ewaluowane na powierzchni mcp (surface), zanim zostanie przesłane do nadrzędnego.

​
5. Gdzie to pasuje

Klucz gateway uwierzytelnia trasy bramy. Nie zastępuje sesji konsoli, której używasz do autorowania polityki: tworzenie polityk, edycja reguł, rejestrowanie serwerów MCP i rozstrzyganie zatwierdzeń wszystko działa pod twoją własną sesją na /api/workspace/firewall/* (odczyty ustawień, polityki i wykrytych narzędzi otwarte dla każdego członka; piaskownica testowa dry-run i wszystkie zapisy wymagają Developer+). Klucz gateway niesie tylko żądania werdyktu i dyspozycję MCP z twojego środowiska maszyna-do-maszyny.

Zakres: klucze, polityki, przestrzenie robocze

Jak firewall_policy_id klucza i zakres gateway odnoszą się do granicy przestrzeni roboczej.

Zatwierdzenia

Przepływ wstrzymanego wywołania, który twój klucz gateway odpytuje i ponownie wysyła.

Webhook zatwierdzeń

Podpisany HMAC callback, który rozstrzyga wstrzymane wywołanie poza pasmem.

Serwery MCP

Rejestruj i zarządzaj serwerami MCP za endpointem bramy.

​
6. FAQ

Podniesienie is_firewall_gateway do true to Admin+. Zapis roli Developer, który ustawia flagę, jest po cichu trzymany na false (więc niepowiązana zmiana nazwy lub edycja kwoty w tym samym żądaniu wciąż się udaje) — klucz po prostu nie poniesie zakresu. Utwórz go ponownie lub edytuj jako Admin.
Prezentowany klucz nie jest w zakresie gateway. Potwierdź, że został wybity z is_firewall_gateway = true przez Admina — zwykły klucz relay zawsze dostaje 403 na tych trasach. Zobacz §2.
Technicznie klucz w zakresie gateway może też obsługiwać ruch relay /v1/*, ale trzymaj je osobno: jeden klucz relay (z przypiętym firewall_policy_id) dla modeli, jeden klucz gateway dla tras evaluate/MCP/zatwierdzeń. Niezależna rotacja, mniejszy promień rażenia.
Klucze są maskowane po utworzeniu, a odczyt jawnego tekstu klucza gateway to Admin+. Jeśli nie skopiowałeś go w czasie wybicia, utwórz nowy klucz gateway i wycofaj stary.