1. Tại sao dùng api key có phạm vi cho LLM agent
Một API key chung là một bearer credential: ai giữ nó đều có thể gọi bất kỳ mô hình nào, từ bất cứ đâu, với bất kỳ khoản tiền nào, không gắn chính sách nào. Đó là điều ngược lại với những gì một agent tự chủ cần. Trên OrcaRouter, một API key không chỉ là một credential — nó là một khai báo phạm vi. Mỗi key mang theo các ràng buộc riêng (những mô hình nào, những IP nào, bao nhiêu chi tiêu, khi nào hết hạn) và trỏ tới guardrail và chính sách firewall chi phối traffic của nó. Chỉnh sửa chính sách mà một key trỏ tới có hiệu lực ở request kế tiếp, không triển khai lại và không đổi code agent. Nguyên tắc là least agency (quyền tối thiểu): trao cho mỗi agent danh tính hẹp nhất vẫn cho phép nó hoàn thành công việc, và không gì hơn. Một key, một agent, một mục đích.2. Một key có phạm vi mang theo những gì
Mỗi key là một gói các giới hạn cộng với hai phần đính kèm chính sách. Mỗi trường được tài liệu hóa trên trang riêng của nó — các liên kết spoke bên dưới dẫn tới phần chuyên sâu.Giới hạn mô hình
model_limits giới hạn một key vào một danh sách mô hình có tên. Một
cuộc gọi ngoài danh sách bị từ chối trước khi nó rời khỏi gateway —
agent không thể chuyển sang một mô hình đắt hơn hoặc mạnh hơn.Danh sách IP cho phép
allow_ips ghim một key vào các địa chỉ nguồn cụ thể. Một key bị rò rỉ
được trình từ bất cứ nơi nào khác sẽ bị từ chối ở tầng auth.Quota, mức trần & hết hạn
credit_limit_usd giới hạn chi tiêu trọn đời (0 = không giới hạn);
expired_time đặt một mốc hết hạn tuyệt đối (-1 = không bao giờ).Môi trường
environment là một nhãn tự do (prod, staging, dev) để tổ chức
các key và lọc log.Gắn chính sách
guardrail_id và firewall_policy_id gắn một chính sách nội dung và
một chính sách cuộc gọi tool vào key. Không gắn thì fallback về mặc
định của workspace.Đối tượng token
Tham chiếu đầy đủ từng trường cho một key, bao gồm
remain_quota / used_quota và is_firewall_gateway.Bị giới hạn vs không giới hạn. Một key với
credit_limit_usd: 0 và
expired_time: -1 không có mức trần chi tiêu và không bao giờ hết hạn —
tiện lợi, nhưng bán kính ảnh hưởng tệ nhất nếu nó rò rỉ. Xem
không giới hạn vs bị giới hạn để
biết khi nào mỗi cái phù hợp.3. Một key least-agency cụ thể
Một agent theo lịch tóm tắt các ticket hỗ trợ bằng một mô hình rẻ và chạy từ một host gần như không cần agency nào. Một key được định phạm vi tốt cho nó:| Trường | Giá trị | Tại sao |
|---|---|---|
model_limits | một mô hình tóm tắt | không thể leo lên một mô hình frontier |
allow_ips | CIDR egress của scheduler | một key bị rò rỉ vô dụng ở nơi khác |
credit_limit_usd | một mức trần hằng tuần | một vòng lặp mất kiểm soát không thể rút cạn số dư |
expired_time | kết thúc của lần triển khai | tự hết hạn, không thể tồn dư |
guardrail_id | một guardrail che PII | văn bản request được sàng lọc |
firewall_policy_id | chỉ allow-list các tool nó cần | không có cuộc gọi tool bất ngờ |
4. Gắn hai mặt phẳng chính sách
Hai phần đính kèm là các trường mạnh nhất trên một key, và chúng phân giải khác nhau khi một chính sách đã gắn bị tắt:guardrail_id — sàng lọc nội dung
guardrail_id — sàng lọc nội dung
Sàng lọc văn bản request và response (PII, secrets, prompt
injection) đối với một guardrail có thứ tự,
theo phạm vi workspace. Phân giải: một
guardrail_id tường minh, được
bật sẽ áp dụng; một cái bị tắt là công tắc tắt — nó không
fallback về mặc định của workspace. Không có phần đính kèm thì guardrail
mặc định của workspace áp dụng, ngược lại không có gì.firewall_policy_id — thực thi cuộc gọi tool
firewall_policy_id — thực thi cuộc gọi tool
Chi phối các hành động một agent thực hiện — cuộc gọi tool, dispatch
MCP, egress — đối với một chính sách firewall
theo phạm vi workspace. Phân giải khác với guardrails: một chính sách
firewall đã gắn bị tắt sẽ fallback về mặc định của workspace,
nó không tắt việc thực thi.
is_firewall_gateway — một loại key khác
is_firewall_gateway — một loại key khác
Một token có phạm vi gateway chỉ được phát hành cho các route Firewall
MCP và evaluate-hook (
/api/v1/firewall/*), không bao giờ cho inference.
Một key thông thường nhận 403 ở đó. Bật cờ này, và đọc plaintext của
gateway key, yêu cầu Admin+.5. Phần keys
Quản lý key
Tạo, chỉnh sửa, và thu hồi key trong console.
Xoay vòng
Xoay vòng một key mà không gián đoạn.
Key hết hạn
Các key ngắn hạn cho agent tạm thời và lần chạy CI.
Che key
Key bị che khi hiển thị; plaintext chỉ hiện một lần lúc tạo.
Key bị rò rỉ
Phải làm gì ngay khi một key bị lộ.
Checklist least-agency
Cho mọi key đi qua cùng một lượt làm cứng.
6. Vị trí của key trong control stack
Một key có phạm vi là lớp phòng thủ đầu tiên — nó quyết định caller là ai và nó có thể vươn tới đâu trước khi bất kỳ chính sách nào chạy. Guardrails và Firewall là các lớp tiếp theo.Bảo mật AI agent
Tại sao danh tính agent là nền tảng của control stack.
Guardrails vs Firewall
Hai mặt phẳng chính sách mà một key có thể gắn vào.
Quyền quá mức
Mối đe dọa mà các key least-agency được xây dựng để kiềm chế.