← Tất cả bài viết
Hướng dẫn

Cách luân chuyển UnifyPort API Key không gây gián đoạn

Để luân chuyển UnifyPort API Key mà không làm gián đoạn dịch vụ, đừng gọi rotate endpoint ngay từ đầu. Khi POST /v1/api-keys/{key_id}/rotate thành công, key cũ mất hiệu lực ngay. Thay vào đó, hãy tạo một key active thứ hai, lưu secret mới chỉ được hiển thị một lần, triển khai nó tới mọi thành phần gọi API, kiểm tra bằng GET /v1/workspace, rồi mới đặt key cũ thành inactive.

Điểm chính

  • Rotate endpoint chuyển đổi ngay lập tức và không có thời gian gia hạn cho key cũ.
  • Quy trình không gián đoạn cần hai key active trong thời gian ngắn: tạo, triển khai, xác minh, vô hiệu hóa.
  • Secret đầy đủ của key mới chỉ xuất hiện một lần trong data.api_key và không thể lấy lại sau đó.
  • Danh sách key chỉ trả về metadata như key_prefix và trạng thái.
  • Với rolling deployment thông thường, hãy tạo key mới rồi vô hiệu hóa key cũ. Chỉ dùng rotate khi cần thu hồi ngay lập tức.

Vì sao gọi rotate trước có thể làm production gián đoạn

Tài liệu Rotate API key định nghĩa thao tác:

POST /v1/api-keys/{key_id}/rotate

Thao tác này tạo một key record mới, trả secret mới một lần và đồng thời làm key cũ mất hiệu lực ngay. Hành vi đó phù hợp khi credential cũ có thể đã bị lộ. Tuy nhiên, nếu web process, queue worker, scheduled job hoặc instance ở region khác vẫn đọc giá trị cũ, chúng có thể nhận 401 invalid_api_key.

Rolling deployment vốn có khoảng thời gian config cũ và mới cùng tồn tại. Việc cắt credential tức thời loại bỏ khoảng giao nhau đó, nên ứng dụng vẫn khỏe cũng có thể gặp lỗi xác thực.

NIST SP 800-53 đưa việc thay đổi hoặc làm mới authenticator vào bối cảnh quản lý authenticator nói chung. Tuy vậy, trình tự vận hành phải dựa trên contract thực tế của sản phẩm: UnifyPort hỗ trợ nhiều API key record, còn rotate làm key trước đó mất hiệu lực ngay.

Runbook luân chuyển API Key không gián đoạn

1. Kiểm kê mọi thành phần đang gọi API

Liệt kê tất cả component gửi X-Api-Key tới https://api.unifyport.ai: ứng dụng public, background worker, tác vụ webhook có gọi API trả lời, scheduled job, công cụ production và health check.

Đừng nhầm API Key với signing_secret của webhook. API Key xác thực request từ hệ thống của bạn tới UnifyPort REST API. signing_secret dùng để kiểm tra webhook được gửi vào endpoint của bạn. Luồng thứ hai được trình bày riêng trong hướng dẫn Webhook HMAC, chống phát lại và retry.

Kiểm tra các record hiện có bằng List API keys:

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

Response cung cấp id, name, key_prefix và status, nhưng không tiết lộ secret đầy đủ.

2. Tạo key active thứ hai

Dùng Create API key thay vì rotate:

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

Response 201 thành công trả metadata trong data.key và secret mới đầy đủ trong data.api_key. Hãy lưu trực tiếp vào hệ thống quản lý secret đã được phê duyệt. Không in giá trị vào deployment log, ticket hay tin nhắn nội bộ.

Nếu mất giá trị một lần này trước khi triển khai, hãy tạo key khác và vô hiệu hóa record không dùng. Không thể khôi phục secret từ prefix.

3. Chứng minh key mới hoạt động trước khi triển khai

Dùng secret mới cho một request chỉ đọc:

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

Response thành công xác nhận key mới trỏ đúng workspace. Tuy nhiên, nó chưa chứng minh mọi application instance đã tải giá trị mới.

Tiếp theo, cập nhật secret reference trong deployment và triển khai lần lượt tới từng nhóm caller. Giữ key cũ ở trạng thái active trong giai đoạn này. Với đội ngũ tại Việt Nam vận hành đồng thời Zalo, WhatsApp và LINE, cần kiểm tra worker dùng chung, job ban đêm và luồng trả lời của cả ba kênh, không chỉ service chính.

4. Xác minh toàn bộ hệ thống dùng credential mới

Trước khi tắt key cũ, hãy kiểm tra:

  • web và API instance đã triển khai xong;
  • queue consumer đã restart hoặc reload config;
  • scheduled job sẽ đọc secret mới ở lần chạy tiếp theo;
  • luồng gửi hoặc trả lời tin nhắn thực hiện được request đã xác thực;
  • không có emergency script phụ thuộc vào giá trị cũ được chép cục bộ.

Hãy dựa vào kết quả request phía ứng dụng và trạng thái deployment. Danh sách key của UnifyPort chỉ hiển thị metadata và trạng thái; tài liệu không mô tả dữ liệu “lần dùng cuối” theo từng key. Không nên suy luận quá trình chuyển đổi đã hoàn tất từ field mà endpoint không trả về.

Nếu nhóm của bạn bắt đầu từ giao diện quản lý, bài giới thiệu dashboard và quản lý API Key cung cấp bối cảnh chung. Runbook này bổ sung thứ tự triển khai cho hệ thống đang hoạt động.

5. Vô hiệu hóa key cũ

Sau khi mọi caller đã dùng secret mới, dùng key mới để gọi Update API key status:

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

Hai trạng thái được tài liệu hóa là active và inactive. Sau khi tắt, thực hiện một request chỉ đọc có kiểm soát bằng secret cũ và xác nhận nhận 401 invalid_api_key. Không dùng tác vụ khách hàng thật làm phép thử.

Cuối cùng, xóa giá trị cũ khỏi deployment config, file môi trường cục bộ, biến CI và tài liệu chuyển đổi tạm thời. Hồ sơ vận hành chỉ nên giữ dữ liệu không nhạy cảm: key ID, tên, trạng thái, người phụ trách và thời gian cutover.

Khi nào nên dùng rotate tức thời

Hãy dùng POST /v1/api-keys/{key_id}/rotate khi việc làm credential cũ mất hiệu lực ngay là yêu cầu chính, chẳng hạn nghi ngờ secret đã bị lộ hoặc mọi caller có thể chuyển đồng thời trong maintenance window.

Khi đó, trình tự là:

  1. dừng hoặc cô lập caller vẫn giữ key cũ;
  2. gọi rotate từ đường vận hành được kiểm soát;
  3. lưu data.api_key một lần;
  4. cập nhật mọi secret consumer;
  5. mở lại traffic và kiểm tra xác thực.

Phương án này ưu tiên tốc độ thu hồi hơn tính liên tục. Nếu nghi ngờ credential bị lộ, không nên kéo dài thời gian hai key cùng active chỉ để duy trì traffic; hãy tuân theo quy trình incident của đội ngũ.

Giới hạn và đánh đổi

Trong khoảng giao ngắn, cả hai credential active đều có thể xác thực vào workspace. Hãy giữ khoảng này ngắn nhất có thể và giới hạn người hoặc hệ thống đọc secret. Tài liệu giới thiệu UnifyPort nêu rằng X-Api-Key được phân giải tới một workspace và cấp quyền trong workspace đó; đây không phải quá trình chuyển quyền theo từng endpoint.

Runbook này cũng không thay signing_secret của webhook, thông tin đăng nhập nền tảng hoặc imported session. Mỗi loại secret có consumer và kiểu lỗi khác nhau, vì vậy nên thay đổi và kiểm tra riêng.

FAQ

UnifyPort API Key rotation có thời gian gia hạn không?

Rotate endpoint được tài liệu hóa không có thời gian gia hạn. Key cũ mất hiệu lực ngay khi thao tác thành công. Nếu cần khoảng giao, hãy tạo key thứ hai trước.

Có thể lấy lại API Key mới sau đó không?

Không. Giá trị đầy đủ chỉ được trả một lần trong data.api_key. Danh sách sau đó chỉ hiển thị prefix, trạng thái và metadata khác.

Kiểm tra key mới an toàn bằng cách nào?

Gọi GET /v1/workspace với X-Api-Key mới, sau đó xác nhận mọi caller đã triển khai đều nạp cùng secret trước khi tắt record cũ.

Nên dùng rotate hay tạo rồi vô hiệu hóa?

Dùng tạo rồi vô hiệu hóa cho rolling deployment bình thường. Dùng rotate khi chủ đích là thu hồi ngay và đã cô lập mọi caller dùng key cũ.

API Key có giống signing_secret không?

Không. X-Api-Key xác thực lệnh gọi REST API; signing_secret dùng để kiểm tra chữ ký HMAC-SHA256 của webhook.

Bước tiếp theo

Mở Create API key reference, tạo credential production song song và hoàn thành năm cổng kiểm tra trước khi đổi trạng thái key cũ.

Nguồn

Đã kiểm tra ngày 17 tháng 8 năm 2026.