Chuyển đến nội dung chính
Mọi request đến OrcaRouter đều mang theo một API key. Key đó không chỉ là credential — nó là một khai báo phạm vi: mô hình nào caller có thể dùng, IP nào có thể trình nó, bao nhiêu nó có thể tiêu, và chính xác guardrail và chính sách firewall nào quản lý traffic của nó. Trang này giải thích hệ thống phân cấp ba cấp và cách chính sách phân giải tại thời điểm request.

​
1. Ba phạm vi

Ba khái niệm lồng vào nhau:
  • Workspace — ranh giới tenant. Mọi thành viên của một workspace chia sẻ cùng danh mục chính sách guardrail và firewall. Không có gì vượt qua ranh giới workspace — một chính sách được soạn trong workspace A vô hình với workspace B.
  • Chính sách — một tập quy tắc có tên, theo phạm vi workspace (guardrail hoặc chính sách firewall). Chỉnh sửa một chính sách có hiệu lực trên mọi key được gắn với nó ở request tiếp theo, mà không cần triển khai lại.
  • Key — danh tính cộng với gắn kết. Một key mang theo các ràng buộc riêng của nó và trỏ đến các chính sách quản lý nó.
Workspace là ranh giới ngoài; chính sách là tài nguyên chia sẻ bên trong nó; key là danh tính theo từng agent kết nối các ràng buộc và chính sách lại với nhau.

​
2. Những gì key mang

Mỗi API key là một gói giới hạn và gắn kết. Đặt chúng trong key editor (/console/token) — tạo hoặc chỉnh sửa key yêu cầu vai trò Developer hoặc cao hơn.
TrườngNhững gì nó giới hạnVai trò tối thiểu để đặt
model_limitsGiới hạn key với một danh sách mô hình cụ thể — bất kỳ cuộc gọi nào ngoài danh sách đó bị từ chối trước khi rời gateway.Developer
allow_ipsIP allow-list. Request từ bất kỳ địa chỉ không có trong danh sách bị từ chối tại lớp xác thực. Trống có nghĩa là tất cả IP được phép.Developer
credit_limit_usdGiới hạn chi tiêu tính bằng USD. 0 có nghĩa là không giới hạn. Gateway thực thi điều này dựa trên mức chi tiêu lifetime của key.Developer
expired_timeTimestamp hết hạn tuyệt đối. -1 có nghĩa là key không bao giờ hết hạn.Developer
environmentMột nhãn freeform (vd: prod, staging, dev) để tổ chức key và lọc log.Developer
guardrail_idGắn một guardrail cụ thể với key này. Mọi cuộc gọi mà key này thực hiện đều được sàng lọc bởi guardrail đó.Developer
firewall_policy_idGắn một chính sách firewall cụ thể với key này. Mọi lời gọi tool mà key này phát ra đều được đánh giá bởi chính sách đó.Developer
is_firewall_gatewayĐánh dấu key là token có phạm vi gateway — bắt buộc để gọi các route MCP dispatch và evaluate-hook. Một key thông thường nhận 403 trên các route đó. Đọc plaintext gateway key yêu cầu Admin.Admin (để bật và đọc plaintext)
Key được mask khi hiển thị trong console. Plaintext được hiển thị một lần khi tạo; gateway-scoped key yêu cầu Admin để lấy lại.

​
3. Thứ tự phân giải chính sách

Đối với bất kỳ request nào, OrcaRouter phân giải guardrail đang hoạt động và chính sách firewall độc lập:
  1. Gắn key — nếu key có guardrail_id tường minh (hoặc firewall_policy_id) và chính sách đó tồn tại và được bật, nó áp dụng.
  2. Mặc định workspace — nếu key không có gắn kết, guardrail is_default đã bật (hoặc chính sách) của workspace áp dụng.
  3. Không có thực thi — nếu không cái nào được đặt, request đi qua mà không có sàng lọc nội dung hoặc thực thi lời gọi tool.
Hai mặt phẳng khác nhau khi một chính sách được gắn bị disabled:
  • Một gắn kết guardrail bị vô hiệu hóa hoặc xóa có nghĩa là key không có guardrail — vô hiệu hóa nó là công tắc tắt; nó không fallback về mặc định workspace.
  • Một gắn kết firewall bị vô hiệu hóa fallback về chính sách firewall mặc định workspace — nên việc vô hiệu hóa một gắn kết firewall hoàn trả key về mặc định workspace, nó không tắt thực thi.
Một gắn kết missing (0/unset) luôn fallback về mặc định workspace; không cái nào được đặt có nghĩa là không có thực thi.
Nhiều nhất một guardrail và một chính sách firewall mỗi workspace có thể là mặc định tại bất kỳ thời điểm nào. Thăng cấp một mặc định mới sẽ hạ cấp cái cũ trong cùng một transaction — bạn không bao giờ vô tình có hai mặc định.

​
4. Key tối thiểu quyền — một key mỗi agent

Cấu hình an toàn nhất là cho mỗi agent key hẹp phạm vi của riêng nó thay vì chia sẻ một key workspace duy nhất cho tất cả caller. Một key được phạm vi tốt cho agent chỉ gọi một mô hình và chạy các tác vụ theo lịch có thể trông như:
  • model_limits: ["openai/gpt-4o-mini"] — agent không thể chuyển sang mô hình đắt tiền hơn hoặc có khả năng cao hơn.
  • allow_ips: CIDR egress của scheduler — không có nguồn nào khác có thể trình key này.
  • credit_limit_usd: trần ngân sách hàng tuần — một vòng lặp mất kiểm soát không thể cạn kiệt số dư workspace.
  • expired_time: cuối sprint hoặc vòng đời triển khai — key hết hạn tự động và không thể tái sử dụng.
  • guardrail_id: một guardrail dành riêng cho độ nhạy dữ liệu của agent này — chặt hơn mặc định workspace.
  • firewall_policy_id: một chính sách chỉ allow-list các tool mà agent này hợp pháp cần.
Khi agent này bị xâm phạm qua prompt injection, blast radius bị giới hạn: nó chỉ có thể gọi một mô hình, chỉ từ một dải IP, chỉ đến giới hạn chi tiêu của nó, và chỉ các tool mà chính sách firewall của nó cho phép. Phần còn lại của workspace không bị ảnh hưởng.
Tạo gateway-scoped key (is_firewall_gateway) chỉ cho bề mặt MCP-dispatch hoặc evaluate-hook — không bao giờ cho traffic inference chung. Một gateway key trên inference path cho caller quyền truy cập các route /api/v1/firewall/*, đây là khả năng rộng hơn mức cần. Một key, một mục đích.

​
5. Nơi chính sách được soạn

Guardrails và chính sách firewall đều có phạm vi workspace và được chia sẻ trên tất cả thành viên, nhưng các thay đổi yêu cầu đúng vai trò:
  • Đọc bất kỳ guardrail, chính sách, hoặc key — mọi thành viên workspace.
  • Tạo hoặc thay đổi guardrail, chính sách firewall, MCP server, autonomy level, hành động phê duyệt, và API key thông thường — Developer+.
  • Bật is_firewall_gateway trên một key; đọc plaintext gateway key — Admin+.
Workspace là ranh giới cộng tác: mọi người đều có thể thấy danh mục chính sách; chỉ Developer và cao hơn mới có thể thay đổi nó; chỉ Admin mới có thể cấp gateway credential.

​
6. Tiếp theo

Secure Agents Baseline

Tư thế khởi đầu được khuyến nghị — một công tắc autonomy-level, rồi tinh chỉnh từ traffic thực tế.

Lấy API key

Tạo key đầu tiên của bạn và gắn guardrail hoặc chính sách firewall trong console.
Phạm vi là nền tảng của control stack. Key có phạm vi càng hẹp, blast radius càng nhỏ nếu bất kỳ agent nào bị xâm phạm — và audit trail càng rõ ràng cho thấy mỗi agent được phép làm gì.