Chuyển đến nội dung chính
Một credential dài hạn là một trách nhiệm pháp lý lớn dần một cách lặng lẽ: agent bị ngừng vận hành, demo kết thúc, nhà thầu chuyển đi — nhưng key vẫn hoạt động cho đến khi ai đó nhớ thu hồi nó. Một api key hết hạn lật ngược mặc định đó. Bạn đặt một ngày kết thúc khi bạn đúc key, và OrcaRouter ngừng ủy quyền nó ngay thời khắc ngày đó qua đi — không có tác vụ dọn dẹp nào để quên, không có cửa sổ bị-rò-rỉ-nhưng-vẫn-sống. Hết hạn là một trường trên đối tượng token: expired_time. Trang này là hướng dẫn tập trung cho một điều khiển đó. Để biết phía mức-trần-chi-tiêu của cùng màn hình, xem Quota, mức trần & hết hạn.

​
1. Tại sao đặt một api key hết hạn

Điểm mấu chốt của một key giới hạn thời gian là biến kết quả an toàn thành kết quả mặc định. Một vài trường hợp nó được việc:

Agent tạm thời

Một job theo lịch hoặc agent ngắn hạn nhận một key chết cùng vòng đời triển khai. Một cron task bị quên không thể cứ tiêu tiền nhiều tháng sau.

Demo & dùng thử

Trao một prospect một key hoạt động trong suốt thời gian đánh giá rồi tự tắt — không cần thu hồi theo sau.

Nhà thầu & nhà cung cấp

Định phạm vi một credential vào cửa sổ hợp tác. Khi hợp đồng kết thúc, key cũng vậy.

Truy cập theo phạm vi sự cố

Cấp một key hẹp, ngắn hạn trong một sự cố để truy cập nâng cao không thể tồn tại lâu hơn chính sự cố.
Hết hạn ghép tự nhiên với phần còn lại của một key least-agency — một danh sách mô hình cho phép, một danh sách IP cho phép, và một mức trần chi tiêu. Mỗi cái ràng buộc một trục khác nhau; cùng nhau chúng giữ cho bán kính ảnh hưởng của một key bị xâm phạm nhỏ. Xem Checklist least-agency.

​
2. Trường expired_time

Mốc hết hạn của một key nằm trong một trường duy nhất trên đối tượng token:
TrườngKiểuÝ nghĩa
expired_timeUnix timestamp (giây)Thời khắc tuyệt đối key ngừng ủy quyền. -1 nghĩa là không bao giờ hết hạn.
Hai điều cần ghi nhớ:
  • expired_time là tuyệt đối, không phải một khoảng thời lượng. Bạn đặt thời khắc key chết, không phải “30 ngày kể từ bây giờ” — bộ chọn ngày của console tính timestamp cho bạn.
  • Mặc định cho một key mới là -1 (không bao giờ). Một key chỉ hết hạn nếu bạn cho nó một timestamp thực; để trường không động vào sẽ đúc một key không hết hạn.
Một key không hết hạn (expired_time = -1) là lựa chọn đúng chỉ cho một credential mà bạn chủ động xoay vòng. Nếu bạn có thể nêu tên ngày một key nên ngừng hoạt động — và với agent, demo, và nhà thầu bạn thường có thể — hãy đặt nó. Một key -1 không được canh chừng là cái dễ tồn tại lâu hơn mục đích của nó nhất.

​
3. Đặt một mốc hết hạn trong console

Đặt một mốc hết hạn là một hành động console trên session / access token của bạn — không phải thứ bạn truyền trên một cuộc gọi relay. Tạo hoặc chỉnh sửa một key yêu cầu vai trò Developer trở lên.
  1. Mở Keys (/console/token) và tạo một key mới, hoặc chỉnh sửa một cái hiện có.
  2. Trong trường expiry, chọn ngày và giờ key nên ngừng hoạt động. Để trống (hoặc đặt never) để giữ key vĩnh viễn.
  3. Lưu. Thay đổi có hiệu lực ngay lập tức — không triển khai lại, không đổi code agent.
Chỉnh sửa mốc hết hạn trên một key hiện có là trực tiếp: gia hạn một key sắp hết hiệu lực, hoặc kéo mốc hết hạn của nó về sớm hơn để cho nó nghỉ sớm hơn, và hạn chót mới áp dụng ở request kế tiếp.
Chỉ các cuộc gọi relay /v1/* mang theo key sk-orca-…. Mốc hết hạn bạn đặt ở đây chi phối relay key đó, nhưng bạn cấu hình nó từ session console, không bao giờ bằng cách gửi relay key tới một management route.

​
4. Một key đã hết hạn làm gì

Khi một key được trình sau khi expired_time của nó đã qua, gateway từ chối nó ở tầng auth — request không bao giờ đến một mô hình, nên nó không tốn quota. Trạng thái của key chuyển sang Expired, một trong các trạng thái kết thúc tự động mà một key có thể đạt tới:
Trạng tháiĐạt tới ra sao
EnabledĐang hoạt động; các request được ủy quyền.
DisabledBạn tạm dừng nó; có thể đảo ngược.
ExpiredQuá expired_time của nó — đạt tới tự động.
ExhaustedVượt mức trần quota / chi tiêu — đạt tới tự động.
Expired là kết thúc theo nghĩa key sẽ không tự ủy quyền lại nữa. Nếu bạn cần nó trở lại, chỉnh sửa key để đẩy expired_time vào tương lai (Developer+) và nó trở về Enabled ở request kế tiếp — key, các giới hạn của nó, và các phần đính kèm chính sách của nó đều được bảo toàn. Để cho một key nghỉ vĩnh viễn thay vào đó, thu hồi nó.
Hết hạn vs. vô hiệu hóa vs. thu hồi. Hết hạn là công tắc tắt theo lịch — bạn quyết định hạn chót ngay từ đầu và bỏ đi. Vô hiệu hóa là lần tạm dừng thủ công, có thể đảo ngược cho một sự cố. Thu hồi (xóa) là vĩnh viễn. Hãy với tới hết hạn bất cứ khi nào bạn đã biết khi nào một credential nên ngừng quan trọng.

​
5. Một ví dụ chi tiết: một key demo hai tuần

Giả sử bạn đang trao một prospect một key cho một đánh giá 14 ngày. Bạn muốn nó gọi một mô hình rẻ, tiêu không quá một ngân sách cố định, và tự tắt khi đợt dùng thử kết thúc — tất cả mà không cần một lời nhắc lịch để thu hồi nó. Trong hộp thoại New key, đặt:
  • model_limits: ["openai/gpt-4o-mini"] — demo không thể với tới một mô hình đắt hơn.
  • credit_limit_usd: một ngân sách dùng thử cố định — một vòng lặp mất kiểm soát không thể vượt qua nó.
  • expired_time: kết thúc của cửa sổ 14 ngày — key ngừng ủy quyền tự thân khi đợt dùng thử kết thúc.
Sau hạn chót, bất kỳ request nào nữa trên key này đều bị từ chối mà không tốn quota, và key hiển thị Expired trong danh sách. Không có gì để bạn dọn dẹp; credential tự cho mình nghỉ. 
# Before expiry — authorized
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role":"user","content":"ping"}]}'

# After expiry — the same call is rejected at the auth layer,
# the model is never invoked, and no quota is consumed.

​
6. Ai có thể làm gì

Hết hạn bị chi phối bởi cùng cổng vai trò như phần còn lại của vòng đời một key, theo phạm vi workspace đang hoạt động của bạn:
Hành độngVai trò tối thiểu
Xem mốc hết hạn của một keyViewer
Đặt hoặc thay đổi expired_time (tạo / chỉnh sửa một key)Developer
Tiết lộ lại plaintext của một key thông thườngDeveloper
Đọc plaintext của một key có phạm vi gateway (is_firewall_gateway)Admin
Để biết toàn bộ vòng đời — tạo, vô hiệu hóa, thu hồi — và khuôn mẫu xoay vòng ghép với hết hạn, xem Quản lý key.

​
7. Bước tiếp theo

Quota, mức trần & hết hạn

Người anh em mức-trần-chi-tiêu của hết hạn — ràng buộc một key bằng đô la cũng như bằng thời gian.

Xoay vòng key

Việc chuyển giao không gián đoạn giữ cho một key không hết hạn khỏi tồn tại mãi.

Đối tượng token

Mọi trường mà một key mang theo, bao gồm expired_time, và mỗi cái ràng buộc điều gì.

Checklist least-agency

Kết hợp hết hạn với giới hạn mô hình, danh sách IP cho phép, và mức trần chi tiêu cho một key có bán kính ảnh hưởng tối thiểu.
Một key biết khi nào dừng là một credential nữa bạn không phải nhớ cho nghỉ. Đặt expired_time bất cứ khi nào bạn có thể nêu tên ngày — và để gateway dọn dẹp cho bạn.