Chuyển đến nội dung chính
Mọi credential dài hạn đều nên được thay thế theo lịch, và ngay lập tức trước bất kỳ dấu hiệu phơi bày nào. Cách an toàn để xoay vòng api key credential không bao giờ là biến đổi một key sống tại chỗ — mà là đúc một cái mới, chuyển traffic lên nó, và cho cái cũ nghỉ một khi không gì còn phụ thuộc vào nó. Làm theo thứ tự đó thì không bao giờ có thời khắc nào không có key hoạt động. Trang này là cẩm nang từng bước. Để biết vòng đời key rộng hơn (tạo / vô hiệu hóa / xóa) xem Quản lý key; để biết mọi trường mà một key mang theo xem Đối tượng token.
Mọi hành động console ở đây nằm ở màn hình Keys (/console/token) và chạy trên session / access token của bạn — không phải relay key. Tạo, chỉnh sửa, vô hiệu hóa, hoặc xóa một key yêu cầu vai trò Developer trở lên. Chỉ các cuộc gọi inference /v1/* dùng relay key sk-orca-….

​
1. Tại sao xoay vòng, và tại sao không bao giờ tại chỗ

Một key trên OrcaRouter là một danh tính bất biến, không chỉ là một chuỗi — nó mang theo danh sách mô hình cho phép, danh sách IP cho phép, mức trần chi tiêu, mốc hết hạn, và phần đính kèm chính sách riêng của nó. Bạn không thể thay đổi vật liệu secret của một key hiện có; credential và các ràng buộc được phát hành cùng nhau lúc tạo. Vậy “xoay vòng” nghĩa là phát hành một cái kế nhiệm và di chuyển lên nó. Làm nó:
  • theo một nhịp cố định cho bất kỳ credential production nào (hàng quý là một baseline phổ biến);
  • ngay thời khắc một key bị nghi rò rỉ — dù với một vụ rò rỉ được xác nhận, hãy cắt nó trước và xoay vòng sau (xem Phản ứng key bị rò rỉ);
  • bất cứ khi nào chủ sở hữu của key (một nhân viên, một tích hợp nhà cung cấp, một agent bị ngừng vận hành) thay đổi.
Plaintext (sk-orca-…) được hiển thị một lần, lúc tạo — sao chép nó khi đó. Về sau console chỉ hiển thị một dạng đã che như orca-7Bf****wxyz. Một Developer+ có thể tiết lộ lại plaintext của một key thông thường sau đó, nhưng một key có phạm vi gateway (is_firewall_gateway) yêu cầu Admin để đọc plaintext của nó lần nữa — nên hãy coi lần tiết lộ đầu tiên của gateway key là bản sao đáng tin cậy duy nhất của bạn.

​
2. Trình tự xoay vòng api key

Toàn bộ điểm mấu chốt là một sự chồng lấp sạch: key mới hoạt động trước khi cái cũ ngừng. Bốn bước.
1

Tạo key kế nhiệm

Đúc một key mới với cùng phạm vi với cái bạn đang thay — cùng model_limits, allow_ips, credit_limit_usd, expired_time, và cùng guardrail_id / firewall_policy_id. Sao chép plaintext ngay lập tức. Xoay vòng là thời khắc lý tưởng để siết chặt phạm vi nữa: bỏ một mô hình agent không còn dùng, hoặc thu hẹp danh sách IP cho phép.
2

Di chuyển traffic

Triển khai sk-orca-… mới tới mọi caller — config, secret manager, CI variable, runtime agent. Tung nó ra cùng cách bạn ship bất kỳ thay đổi secret nào. Cả hai key đều sống tại điểm này, nên các lần triển khai có thể được rải ra mà không gián đoạn.
3

Xác minh key mới đang mang tải

Xác nhận key kế nhiệm thực sự đang phục vụ traffic trước khi bạn động vào cái cũ. Theo dõi used_quota của key mới leo lên trong khi cái của key cũ phẳng ra — usage theo từng key là tín hiệu cắt chuyển của bạn.
4

Cho key cũ nghỉ

Một khi key cũ không cho thấy traffic nào, vô hiệu hóa nó trước (có thể đảo ngược) và canh chừng kẻ rớt lại, rồi xóa nó vĩnh viễn. Vô hiệu hóa là tạm dừng; xóa là điểm không quay lại.
Đặt một nhãn environment trên mỗi key — tái dùng nó trên key cũ và mới, hoặc tăng nó (prod → prod-2026q2) — để key kế nhiệm và tiền nhiệm được gắn nhãn riêng biệt trong khi cả hai cùng sống trong cửa sổ chồng lấp.

​
3. Một lần xoay vòng cụ thể, qua REST

Mọi thứ bên dưới là một hành động console — các management route này chạy dưới session của bạn (UserAuth), không phải relay key. Giả sử bạn đang thay key cho một agent tóm tắt theo lịch. Tạo key kế nhiệm với cùng phạm vi: 
# Console session token — NOT an sk-orca-… relay key
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
  }'
Phản hồi trả về plaintext một lần ("data": "sk-orca-…"). Sao chép nó, triển khai nó tới summarizer, và xác nhận key mới đang phục vụ trước khi tiếp tục. Khi key cũ (id 481) không cho thấy traffic nào, vô hiệu hóa rồi xóa nó: 
# Pause first (reversible) — set the old key's status to 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}'

# Once you're sure nothing depends on it — revoke for good
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
Trạng thái của một key là một trong Enabled (1), Disabled (2), Expired (3), hoặc Exhausted (4). Vô hiệu hóa đặt nó thành Disabled; mọi request mà key thực hiện sau đó bị từ chối trong khi config, phần đính kèm, và lịch sử của nó vẫn nguyên. Xóa là vĩnh viễn — credential không bao giờ có thể ủy quyền một request nữa, và một key đã xóa không thể khôi phục.
Bạn có thể làm tất cả điều này mà không cần API — màn hình Keys có New key, một công tắc Disabled theo từng key, và Delete (đơn lẻ hoặc theo lô). Dạng REST ở trên là để viết script cho các lần xoay vòng theo lịch.

​
4. Xoay vòng key gắn chính sách và gateway

Phần đính kèm guardrail và firewall của một key nằm trên key, nên key kế nhiệm phải mang theo cùng guardrail_id và firewall_policy_id để thực thi cùng tư thế. Hai điều cần biết:
Guardrails và chính sách firewall là các tài nguyên có tên, theo phạm vi workspace, dùng chung trên các key. Xoay vòng một key không động vào chính bản thân chính sách; bạn chỉ đang trỏ lại một key mới vào guardrail_id / firewall_policy_id hiện có. Chính sách tiếp tục chi phối traffic không gián đoạn.
Một key đặt is_firewall_gateway lái các route Firewall gateway (/api/v1/firewall/*). Đúc một cái, và tiết lộ lại plaintext của nó, đều yêu cầu Admin. Vì bạn không thể tùy tiện đọc lại secret của nó, hãy ghi lại plaintext của gateway key mới lúc tạo và lưu nó trong secret manager của bạn trước khi bạn cắt chuyển.
Đừng tái dùng một key đơn lẻ — gateway hay khác — trên nhiều agent và “xoay vòng” bằng cách chỉnh sửa giới hạn. Một key cho mỗi agent giữ mỗi lần xoay vòng cô lập và bán kính ảnh hưởng nhỏ. Xem Checklist least-agency.

​
5. Xoay vòng khẩn cấp (nghi rò rỉ)

Nếu bạn nghĩ một key bị lộ, thứ tự đảo ngược: cầm máu trước, di chuyển sau.
  1. Vô hiệu hóa key nghi ngờ ngay để nó không thể ủy quyền bất cứ gì trong khi bạn điều tra — hoặc xóa nó luôn nếu vụ rò rỉ được xác nhận.
  2. Đúc key kế nhiệm và tung nó ra như ở §2.
  3. Xem xét key bị rò rỉ đã làm gì trước khi bạn cắt nó: lọc request log theo key (token) đó để định phạm vi bán kính ảnh hưởng.
Runbook sự cố đầy đủ nằm ở Phản ứng key bị rò rỉ.
Một expired_time ngắn là bảo hiểm xoay vòng: một key hết hạn tự cho mình nghỉ ngay cả khi bạn quên lần xoay vòng thủ công, giới hạn bao lâu bất kỳ credential đơn lẻ nào có thể bị lạm dụng.

​
6. Bước tiếp theo

Quản lý key

Vòng đời tạo / vô hiệu hóa / thu hồi mà các bước này xây dựng trên.

Gắn chính sách vào một key

Mang cùng guardrail và chính sách firewall lên key kế nhiệm.

Key hết hạn

Đặt một mốc hết hạn để các key tự xoay vòng theo một hạn chót.

Phản ứng key bị rò rỉ

Đường khẩn cấp khi một credential bị lộ.
Xoay vòng chỉ là sự chồng lấp có kỷ luật: một kẻ kế nhiệm hoạt động trước khi tiền nhiệm ngừng. Giữ mỗi key có phạm vi hẹp và việc chuyển giao vẫn buồn tẻ — đó chính xác là điều bạn muốn từ một lần xoay vòng credential.