API

Khóa API của ArchiBot Chat

Tạo, sao chép, xoay vòng và thu hồi các khóa API được tạo, đồng thời kết nối một công cụ cộng tác viên bên ngoài với điểm cuối công khai của ArchiBot.

Quản trị viên khách hàngThành viên khách hàngNgười vận hành nền tảng

Cập nhật lần cuối 18 tháng 6, 2026

Khóa API cho phép bạn gọi điểm cuối công khai ArchiBot từ các script, công cụ tác tử cục bộ và các tích hợp chạy bên ngoài workspace được quản lý. Chúng tách biệt với thông tin xác thực ẩn dùng để cung cấp cho màn hình Chat trên trình duyệt, vốn không bao giờ được hiển thị cho người dùng.

Các workspace ArchiBot được quản lý đã tự động cấp phát khóa riêng của chúng. Chỉ dùng khóa API được tạo cho công cụ tác tử cục bộ, tiện ích mở rộng trình soạn thảo hoặc một harness do khách hàng sở hữu mà cần gọi ArchiBot như một cộng tác viên bên ngoài.

Khi nào nên dùng khóa API

Tạo một khóa được tạo khi bạn cần:

• Gọi ArchiBot từ một script hoặc tác vụ theo lịch.
• Kết nối một công cụ tác tử cục bộ hoặc tiện ích mở rộng trình soạn thảo với điểm cuối.
• Chạy một client tương thích OpenAI trên điểm cuối ArchiBot.
• Kết nối một harness do khách hàng sở hữu bên ngoài workspace với ArchiBot.

Đối với các câu hỏi tương tác, hãy dùng màn hình Chat trên trình duyệt. Xem Sử dụng ArchiBot Chat.

Mở tab API Keys

1. Mở Settings từ thanh điều hướng bên trái.
2. Chọn chế độ xem ArchiBot account.
3. Mở tab API Keys.

Tab này nằm cùng hàng với Setup, Git access, CI & Review, Support, Activity và Billing. Nếu API access chưa được bật cho tài khoản, tab sẽ hiển thị thông báo API access is not enabled for this account. và nút Create key sẽ bị vô hiệu hóa. Hãy yêu cầu một quản trị viên khách hàng hoặc ISM bật trước cổng sản phẩm API. Xem Thiết lập ArchiBot Chat.

Tạo khóa

1. Trong tab API Keys, chọn Create key.
2. Khóa mới xuất hiện ở đầu danh sách, và toàn bộ giá trị của nó được hiển thị một lần trong một callout được tô sáng với nội dung Copy this key now. It will not be shown again.
3. Chọn Copy bên cạnh giá trị khóa.
4. Lưu nó vào trình quản lý bí mật hoặc môi trường chạy được phê duyệt của bạn.

Các khóa được đặt tên tự động (ví dụ: Console generated key 1) và được gán phạm vi api. Giá trị thô chỉ được hiển thị trong callout này. Khi bạn rời khỏi tab hoặc tạo một khóa khác, chỉ còn thấy tiền tố khóa và siêu dữ liệu.

Nếu nút sao chép không thể truy cập clipboard của bạn, tab sẽ hiển thị Clipboard copy unavailable. Hãy chọn thủ công đoạn văn bản khóa và sao chép nó trước khi chuyển sang trang khác.

Kết nối một công cụ cộng tác viên bên ngoài

Thẻ External coworker access tạo một script thiết lập sẵn sàng chạy để bạn không phải ghép các biến môi trường bằng tay.

Thẻ này hiển thị hai trường tham chiếu:

Bên dưới các trường này, phần xem trước hiển thị một script shell xuất các biến môi trường cho endpoint và khóa, rồi chạy một lệnh cộng tác viên mẫu. Khi bạn vừa tạo hoặc xoay vòng một khóa, script sẽ bao gồm giá trị khóa dùng một lần đó; nếu không, nó dùng placeholder <new-api-key>.

1. Tạo hoặc xoay vòng một khóa để trường Key source hiển thị New one-time key included.
2. Chọn Copy setup trên thẻ External coworker access.
3. Dán script vào shell cục bộ, trình quản lý bí mật hoặc cấu hình công cụ của bạn.

Script đặt các biến chuẩn tương thích OpenAI (OPENAI_BASE_URL, OPENAI_API_KEY) cùng với các biến cộng tác viên ArchiBot để cả client tương thích OpenAI và công cụ cộng tác viên ArchiBot đều lấy cùng một endpoint và khóa. Hãy dùng URL endpoint production do ISM cung cấp cho tài khoản của bạn thay vì suy ra từ một ví dụ cục bộ.

Dùng khóa

Dùng khóa như một bearer token với endpoint ArchiBot tương thích OpenAI.

curl https://chat.example.archibot.cloud/v1/responses \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "archibot",
    "input": "Summarize this Archibus request queue export."
  }'

Endpoint chuyển tiếp các trường Responses API tương thích OpenAI như tools, tool_choice, reasoning, metadata và nội dung input có cấu trúc đến endpoint ArchiBot sau khi vượt qua kiểm tra API key và tín dụng.

Đối với phản hồi theo luồng, hãy gửi stream: true:

curl -N https://chat.example.archibot.cloud/v1/responses \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "archibot",
    "input": "Draft a short work plan for this Archibus data cleanup.",
    "stream": true
  }'

Các phản hồi theo luồng trả về bằng chứng thanh toán trong các header phản hồi X-ArchiBot-* thay vì viết lại từng mảnh sự kiện.

Khám phá model tương thích OpenAI sử dụng cùng bearer key:

curl https://chat.example.archibot.cloud/v1/models \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY"

Khám phá model không tính vào hạn mức sử dụng của bạn.

Giới hạn tần suất

Các khóa API được tạo có giới hạn yêu cầu theo từng khóa. Phản hồi bao gồm các header X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Khi vượt quá giới hạn, endpoint trả về 429 cùng header Retry-After.

Hết hạn

Các khóa API được tạo hết hạn sau một năm kể từ khi tạo. Mỗi hàng khóa hiển thị ngày tạo, ngày hết hạn và ngày dùng gần nhất bên cạnh tiền tố khóa.

Các khóa đã hết hạn vẫn hiển thị theo tên, tiền tố và siêu dữ liệu để bạn có thể kiểm tra các tích hợp cũ, nhưng chúng không còn có thể gọi khám phá model hoặc endpoint responses. Việc từ chối khóa đã hết hạn xảy ra trước khi bất kỳ mức sử dụng nào được tính. Hãy xoay vòng một khóa đã hết hạn để phát hành bản thay thế dưới cùng tên và phạm vi, hoặc thu hồi nó nếu tích hợp đã ngừng sử dụng.

Xoay vòng một khóa

Xoay vòng một khóa khi một tích hợp cần tiếp tục chạy dưới cùng tên và phạm vi nhưng giá trị bí mật phải thay đổi.

1. Trong tab API Keys, tìm khóa đang hoạt động theo tên hoặc tiền tố.
2. Chọn Rotate trên hàng của khóa đó.
3. Sao chép giá trị thay thế từ callout dùng một lần.
4. Cập nhật script, mục trong trình quản lý bí mật hoặc môi trường chạy bị ảnh hưởng.

Việc xoay vòng sẽ thu hồi khóa trước đó và tạo một bản thay thế với cùng tên và phạm vi. Giá trị thay thế chỉ được hiển thị một lần, trong cùng callout dùng cho khóa mới. Rotate có hiệu lực ngay; không có hộp thoại xác nhận riêng, vì vậy hãy sẵn sàng cập nhật tích hợp trước khi lưu lượng cũ bị lỗi.

Thu hồi một khóa

Thu hồi một khóa khi:

• Nó không còn được sử dụng.
• Nó đã bị dán vào chat, email, một ticket, một repository hoặc một tài liệu được chia sẻ.
• Chủ sở hữu rời khỏi nhóm.
• Tích hợp đã được thay thế.

1. Trong tab API Keys, tìm khóa theo tên hoặc tiền tố.
2. Chọn Revoke trên hàng của khóa đó.
3. Cập nhật hoặc gỡ bỏ mọi script hoặc tích hợp đã phụ thuộc vào nó.

Revoke có hiệu lực ngay và không có hộp thoại xác nhận riêng, vì vậy hãy xác nhận khóa đó là đúng trước khi bạn chọn Revoke.

Thanh toán

Các khóa API được tạo lấy từ cùng hạn mức sử dụng chat và API được chia sẻ hiển thị trong Billing. Các kiểm tra preflight thất bại và các yêu cầu upstream bị từ chối không nên tiêu tốn tín dụng; một yêu cầu theo luồng sẽ trở thành tính phí khi endpoint ArchiBot chấp nhận luồng. Xem Thanh toán và tín dụng của ArchiBot Chat.

Quy tắc bảo mật

• Không bao giờ commit khóa API vào source control.
• Không bao giờ dán khóa API vào ticket hỗ trợ hoặc tài liệu dùng chung.
• Dùng biến môi trường hoặc trình quản lý bí mật, không dùng giá trị inline.
• Khi có thể, hãy dùng một khóa cho mỗi tích hợp.
• Xoay vòng khóa định kỳ cho các tích hợp chạy dài hạn.
• Thu hồi khóa ngay lập tức nếu nghi ngờ bị lộ.

Thông tin xác thực Chat so với khóa API

Đừng yêu cầu bộ phận hỗ trợ ISM tiết lộ thông tin xác thực ẩn của Chat. Nó được cố ý không hiển thị cho người dùng.

Hướng dẫn liên quan

• Thiết lập ArchiBot Chat
• Sử dụng ArchiBot Chat
• Thanh toán và tín dụng của ArchiBot Chat
• Tổng quan bảo mật ArchiBot Chat
• Cách sử dụng dữ liệu được phê duyệt của ArchiBot Chat