Chuyển đến nội dung chính
Để chạy các cuộc gọi tool qua agent firewall từ bên ngoài relay mô hình — vòng lặp agent của riêng bạn gọi hook evaluate, hoặc một MCP client kết nối tới MCP gateway — bạn xác thực bằng một key phạm-vi-firewall-gateway chuyên biệt, không phải một relay key sk-orca-… thông thường. Một key thường nhận 403 trên các route firewall gateway xác-thực-bằng-token (approval callback là một ngoại lệ — nó ký-HMAC, không cổng-token). Trang này đề cập một firewall gateway api key là gì, cách tạo một cái, và tại sao phạm vi được giới hạn ở Admin+. Để biết bản thân engine, xem tổng quan Firewall và tham chiếu sâu tại Firewall.

​
1. Một firewall gateway api key là gì

Mỗi token (API key) trong workspace của bạn mang một cờ is_firewall_gateway. Khi nó là true, key được phép với tới bề mặt firewall gateway:
RouteNó làm gì
POST /api/v1/firewall/evaluateVerdict tiền-dispatch cho một cuộc gọi tool.
POST /api/v1/firewall/evaluate_planKiểm tra tiền-thực-thi cho một kế hoạch nhiều bước.
ANY /api/v1/firewall/mcpEndpoint MCP gateway hợp nhất.
GET /api/v1/firewall/mcp_serversLiệt kê các MCP server đã đăng ký của workspace (trả về auth thượng nguồn đã giải mã).
GET /api/v1/firewall/approvals/:idPoll trạng thái phê duyệt của một cuộc gọi được giữ.
Một key với is_firewall_gateway = false (mặc định) là một relay key bình thường — nó phục vụ traffic mô hình /v1/* và, nếu bạn đã gắn một chính sách qua firewall_policy_id, các cuộc gọi tool của nó được quản trị inline. Nhưng nó không thể gọi các route gateway ở trên.
Hai key khác nhau, hai việc khác nhau. Relay key của bạn (firewall_policy_id được gắn) là cái mà agent của bạn dùng để nói chuyện với mô hình — firewall quản trị các cuộc gọi tool của nó tự động. Một firewall gateway key là cái mà runtime agent của bạn dùng để hỏi firewall một verdict trực tiếp, hoặc để proxy MCP tools/call qua gateway. Hầu hết các workspace chỉ cần một gateway key một khi họ áp dụng hook evaluate hoặc MCP gateway.

​
2. Tại sao một key thường nhận 403

Phạm vi gateway mở khóa hai khả năng nhạy-cảm-secret, nên nó cố tình được tách khỏi các key thông thường:
  • /evaluate chấp nhận một request_id do-người-gọi-cung-cấp vốn chảy vào event firewall và các bản ghi phê duyệt. Bất kỳ key mô hình nào có thể giả mạo audit event hoặc âm thầm dò kết cục chính sách sẽ làm xói mòn dấu vết.
  • /mcp_servers trả về thông tin xác thực thượng nguồn đã giải mã để proxy của SDK có thể dispatch tới các MCP server đã đăng ký của bạn. Đó là một lần đọc credential, không phải một cuộc gọi mô hình.
Vì điều này, handler kiểm tra cờ is_firewall_gateway của token đang trình và trả về HTTP 403 khi nó vắng mặt: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Đừng tái dùng một relay key lưu-lượng-cao làm một gateway key, và đừng tái dùng một gateway key cho traffic relay. Giữ key mặt-phẳng-hành-động riêng biệt nên bán kính tác động và việc xoay vòng của nó độc lập với các key mô hình của bạn.

​
3. Tạo một cái — giới hạn vai trò ở Admin+

Đặt is_firewall_gateway = true yêu cầu workspace Admin hoặc cao hơn. Một Developer có thể tạo và chỉnh sửa các key thông thường, nhưng không thể tạo một cái phạm-vi-gateway — cờ là một mối quan tâm quản-lý-secret, nên nó nằm trên vai trò ghi-token bình thường. Bạn cấu hình key trong console, dưới các API key của workspace. Để tạo một gateway key:
1

Mở API keys với vai trò Admin

Đăng nhập như một workspace Admin (hoặc cao hơn) và mở trang API keys trong console.
2

Tạo một key với phạm vi gateway

Tạo một key mới và bật phạm vi firewall gateway của nó (is_firewall_gateway). Một session vai-trò-Developer sẽ không thấy phạm vi có hiệu lực — server giữ cờ false cho non-admin.
3

Copy key một lần

Copy giá trị key đầy đủ lúc tạo. Sau đó console che nó khi hiển thị, và đọc lại plaintext của một gateway key tự nó là Admin+ — non-admin nhận các dòng gateway bị bỏ khỏi phản hồi “fetch my keys”.
Hạ cờ rộng rãi hơn nâng nó: xóa is_firewall_gateway (hạ cấp một gateway key trở lại một key bình thường) mở cho bất kỳ vai trò nào có thể chỉnh sửa key. Chỉ nâng nó lên true mới là Admin+.

​
Cổng vai trò trong nháy mắt

Hành độngVai trò
Tạo/chỉnh sửa một key thông thườngDeveloper+
Đặt is_firewall_gateway = trueAdmin+
Đọc lại plaintext của một gateway keyAdmin+
Xóa is_firewall_gateway (hạ cấp)bất kỳ người-chỉnh-sửa-key nào

​
4. Một ví dụ cụ thể

Bạn đang chạy một vòng lặp agent và muốn kiểm tra một cuộc gọi tool trước khi dispatch nó. Là một Admin, tạo một gateway key trong console, rồi gọi hook evaluate từ runtime của bạn với key đó: 
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 phân giải chính sách đang hoạt động của workspace bạn và trả về verdict — allow, audit, deny, sanitize, pending_approval, hoặc một phân giải cap_cost. Agent của bạn hành động trên nó: dispatch khi allow, bỏ qua khi deny, poll approval id khi pending_approval. Cùng gateway key xác thực các route poll-phê-duyệt và MCP.
Trỏ một MCP client (Claude Desktop, Cursor, một framework agent) tới https://api.orcarouter.ai/api/v1/firewall/mcp? Dùng gateway key làm bearer token của nó. Mỗi tools/call khi đó được đánh giá trên bề mặt mcp trước khi nó được chuyển tiếp thượng nguồn.

​
5. Cái này khớp vào đâu

Một gateway key xác thực các route gateway. Nó không thay thế session console mà bạn dùng để soạn chính sách: tạo chính sách, chỉnh sửa quy tắc, đăng ký MCP server, và phân giải phê duyệt tất cả chạy dưới session của riêng bạn trên /api/workspace/firewall/* (đọc cài đặt, chính sách, và discovered- tool mở cho mọi thành viên; test sandbox chạy-thử và mọi thao tác ghi yêu cầu Developer+). Gateway key chỉ mang các request verdict và MCP dispatch từ runtime máy-tới-máy của bạn.

Phạm vi: key, chính sách, workspace

Cách firewall_policy_id của một key và một phạm vi gateway liên quan tới ranh giới workspace.

Phê duyệt

Luồng cuộc-gọi-được-giữ mà gateway key của bạn poll và gửi lại.

Webhook phê duyệt

Callback ký-HMAC phân giải một cuộc gọi được giữ ngoài luồng.

MCP server

Đăng ký và quản trị các MCP server đằng sau endpoint gateway.

​
6. FAQ

Nâng is_firewall_gateway lên true là Admin+. Một thao tác ghi vai-trò-Developer đặt cờ bị âm thầm giữ ở false (nên một lần rename hay chỉnh quota không liên quan trên cùng request vẫn thành công) — key chỉ là không mang phạm vi. Tạo lại hoặc chỉnh sửa nó như một Admin.
Key đang trình không phải phạm-vi-gateway. Xác nhận nó được tạo với is_firewall_gateway = true bởi một Admin — một relay key bình thường luôn nhận 403 trên các route này. Xem §2.
Về kỹ thuật một key phạm-vi-gateway cũng có thể phục vụ traffic relay /v1/*, nhưng hãy giữ chúng riêng biệt: một relay key (với firewall_policy_id được gắn) cho mô hình, một gateway key cho các route evaluate/MCP/phê-duyệt. Xoay vòng độc lập, bán kính tác động nhỏ hơn.
Các key bị che sau khi tạo, và đọc plaintext của một gateway key là Admin+. Nếu bạn không copy nó lúc tạo, hãy tạo một gateway key mới và loại bỏ cái cũ.