Mở đầu — vì sao bài này quan trọng
Ở các bài trước, bạn đã hiểu bức tranh tổng quan về xác thực (Basic, Bearer, API Key) và đã đào sâu vào OAuth 2.0 và JWT. Bài này chúng ta dừng lại ở một cơ chế tưởng chừng đơn giản nhưng lại cực kỳ phổ biến trong thực tế công việc của một BA: API Key.
Tại sao một BA cần nắm chắc về API Key management? Vì đây là chủ đề bạn sẽ chạm vào liên tục trong các dự án tích hợp. Khi công ty bạn ký hợp đồng cho một merchant tích hợp cổng thanh toán, người ta sẽ hỏi "API Key cấp ở đâu, ai giữ, hết hạn khi nào?". Khi đối tác báo "tự nhiên hệ thống chúng tôi gọi API bị lỗi 401", nguyên nhân số một thường là key bị revoke hoặc hết hạn mà không ai báo trước. Khi đội security yêu cầu "rotate toàn bộ key trong 30 ngày", bạn — với vai trò BA — phải hiểu rotate nghĩa là gì, ảnh hưởng đến partner ra sao, và viết được quy trình để không ai mất dịch vụ giữa chừng.
Nói cách khác, OAuth và JWT thiên về người dùng cuối đăng nhập. Còn API Key thiên về hệ thống nói chuyện với hệ thống, đối tác B2B, SDK trên mobile. Vòng đời của một chiếc key — tạo (create), xoay vòng (rotate), thu hồi (revoke) — chính là trọng tâm của bài học này, và nó là một phần kiến thức mà BA giỏi luôn phải có để viết được spec tích hợp chuẩn chỉnh.
Khái niệm cốt lõi
API Key là gì và dùng cho ai?
API Key là một chuỗi ký tự bí mật, dạng như sk_live_a1B2c3D4e5F6g7H8i9J0, đóng vai trò "chứng minh thư" để hệ thống biết ai đang gọi mình. Khác với việc người dùng nhập username/password, API Key thường được cấp cho một client (một ứng dụng, một dịch vụ, một đối tác) chứ không phải cho một con người cụ thể.
Theo đúng ý định gốc của bài, có bốn nhóm đối tượng chính dùng API Key:
- B2B partner — ví dụ một merchant (cửa hàng online) tích hợp cổng thanh toán. Cửa hàng dùng key của họ để gọi API tạo giao dịch. Mỗi merchant một bộ key riêng, để cổng thanh toán biết tiền về tài khoản nào, áp phí gì.
- Internal services — các microservice trong cùng công ty gọi lẫn nhau. Service A cần key để gọi service B, giúp B kiểm soát và ghi log "ai đang gọi tôi".
- Public API có rate limit — ví dụ một API tra cứu thời tiết, tỷ giá, mã bưu chính. Ai muốn dùng phải đăng ký lấy key, và key gắn với hạn mức (ví dụ 1.000 request/ngày cho gói free).
- SDK config trên mobile app — app điện thoại nhúng key để gọi backend hoặc dịch vụ bên thứ ba (Google Maps, Firebase...). Đây là trường hợp nhạy cảm nhất vì key nằm ngay trong app, ai cũng có thể bóc ra được.
API Key khác gì với mật khẩu và token?
Đây là điểm BA hay nhầm. Ba thứ khác nhau:
- Mật khẩu (password): của con người, có thể đổi, thường đi kèm username.
- Token (như JWT, Bearer): thường ngắn hạn, hết hạn sau vài phút đến vài giờ, được cấp lại liên tục thông qua một quy trình đăng nhập/refresh.
- API Key: thường dài hạn, sống nhiều tháng đến nhiều năm, gắn cứng với một client. Chính vì sống lâu nên nó nguy hiểm hơn nếu lộ — và đó là lý do quy trình rotate/revoke trở nên quan trọng.
Vòng đời của một API Key: Create — Rotate — Revoke
Toàn bộ bài này xoay quanh ba động từ:
Create (tạo): Sinh ra một key mới. Điểm mấu chốt — key thường chỉ hiển thị đúng một lần lúc tạo. Sau đó hệ thống chỉ lưu bản hash (mã hóa một chiều) của key, không lưu key gốc. Vì vậy nếu khách làm mất, không ai "lấy lại" được, chỉ có thể tạo key mới. Khi tạo, ta thường gán kèm: phạm vi quyền (scope), hạn mức (rate limit), thời hạn (expiry), môi trường (test/live).
Rotate (xoay vòng): Thay key cũ bằng key mới mà không gây gián đoạn dịch vụ. Đây là phần khó nhất về mặt quy trình. Cách làm chuẩn là dual-key (chấp nhận đồng thời cả key cũ và key mới trong một khoảng giao thời — gọi là grace period), để đối tác có thời gian cập nhật trước khi key cũ bị tắt hẳn.
Revoke (thu hồi): Vô hiệu hóa một key ngay lập tức, không quay lui được. Dùng khi key bị lộ, khi đối tác chấm dứt hợp đồng, hoặc khi nhân viên giữ key nghỉ việc. Sau khi revoke, mọi request dùng key đó sẽ nhận lỗi 401 Unauthorized.
Vài khái niệm đi kèm
- Key prefix: phần đầu của key như
sk_live_(secret-live),pk_test_(public-test). Prefix giúp con người nhìn là biết loại key, và giúp hệ thống quét rò rỉ trên GitHub. - Scope / quyền: một key có thể chỉ được phép đọc, key khác được phép cả ghi. BA nên định nghĩa scope tối thiểu cần thiết (nguyên tắc least privilege).
- Test key vs Live key: tách bạch môi trường thử nghiệm và môi trường thật, để không bao giờ một thao tác test lại trừ tiền thật.
Tình huống thực tế
Tình huống 1 — Cổng thanh toán cấp key cho merchant (B2B partner)
Hãy hình dung một cổng thanh toán Việt Nam, gọi là PayBeo, tương tự VNPay hay MoMo về mô hình. Một sàn thương mại điện tử tên ChợXanh muốn nhận thanh toán online qua PayBeo.
Khi ChợXanh đăng ký, PayBeo cấp cho họ hai cặp key: một bộ test để dev của ChợXanh thử trên môi trường sandbox, một bộ live để chạy thật. Key live trông như sk_live_chx_9f2a..., kèm scope "tạo giao dịch + tra cứu trạng thái" nhưng không có quyền "hoàn tiền" (refund) — vì refund là thao tác nhạy cảm, PayBeo bắt phải cấp riêng key khác với quyền cao hơn và phải qua duyệt.
Sáu tháng sau, một lập trình viên cũ của ChợXanh nghỉ việc, và đội security của ChợXanh phát hiện anh này từng commit nhầm key live vào một repo nội bộ mà nhiều người truy cập được. ChợXanh báo PayBeo. PayBeo hướng dẫn: tạo key live mới trên dashboard, cập nhật vào hệ thống, rồi mới revoke key cũ.
Bài học: Một merchant không bao giờ chỉ có một key "chung chung". Phải tách test/live, tách theo scope (giao dịch vs hoàn tiền), và phải có sẵn quy trình "lộ key thì làm gì". BA của PayBeo chính là người viết ra quy trình self-service này trên dashboard để merchant tự xử lý mà không cần gọi điện cầu cứu.
Tình huống 2 — Rotate hàng loạt vì sự cố bảo mật (Internal services)
Một công ty fintech ở TP.HCM, tạm gọi TíchLũy, có khoảng 25 microservice gọi nhau bằng API Key nội bộ. Một ngày, đội DevOps phát hiện file cấu hình chứa key bị log ra một hệ thống monitoring bên thứ ba do nhầm lẫn. Về lý thuyết key đã "lộ", dù xác suất bị khai thác thấp. Theo chính sách bảo mật, mọi key liên quan phải được rotate trong 72 giờ.
Vấn đề: nếu cứ revoke key cũ rồi mới gắn key mới, sẽ có khoảng thời gian các service không gọi được nhau — toàn hệ thống tê liệt. Đội kỹ thuật áp dụng dual-key rotation:
- Ngày 1: Tạo key mới cho từng service, nạp vào cấu hình song song với key cũ. Hệ thống chấp nhận cả hai.
- Ngày 1–2: Lần lượt cập nhật bên gọi để dùng key mới. Theo dõi log xem còn request nào dùng key cũ không.
- Ngày 3: Khi log cho thấy 0 request dùng key cũ trong 12 giờ, mới revoke key cũ.
Bài học: Rotate không phải là "đổi key" trong một nốt nhạc. Nó là một quy trình có giai đoạn giao thời, có quan sát log, có tiêu chí an toàn để "ngắt" key cũ. BA tham gia dự án này phải viết được runbook (kịch bản vận hành) mô tả từng bước, và đặc biệt phải định nghĩa rõ "tiêu chí nào thì được phép revoke key cũ".
Tình huống 3 — Key nhúng trong mobile app bị bóc ra (SDK config)
Một startup giao đồ ăn tên ĂnLẹ nhúng API Key của một dịch vụ bản đồ vào app Android để hiển thị vị trí tài xế. Sau vài tháng, hóa đơn dịch vụ bản đồ tăng vọt bất thường — gấp 8 lần dự kiến. Điều tra ra: có người đã giải nén file APK, lấy được key, và dùng nó cho dự án riêng của họ, "xài ké" hạn mức của ĂnLẹ.
Đây là bài học kinh điển: mọi key nhúng trong client (mobile/web) đều phải coi như đã công khai. Cách xử lý của ĂnLẹ:
- Revoke key cũ ngay.
- Tạo key mới và giới hạn (restriction): key chỉ chấp nhận request đến từ package name và chữ ký số của app ĂnLẹ; chỉ gọi được đúng các API bản đồ cần dùng; có hạn mức theo ngày.
- Với các thao tác nhạy cảm hơn, chuyển sang gọi qua backend của ĂnLẹ thay vì để app gọi thẳng — backend giữ key thật, app không bao giờ thấy.
Hướng dẫn từng bước
Đây là khung quy trình mà một BA có thể dùng để viết spec hoặc rà soát một hệ thống API Key.
Bước 1 — Phân loại đối tượng dùng key. Liệt kê ai sẽ cần key: partner B2B, internal service, public user, mobile app. Mỗi nhóm có yêu cầu khác nhau về scope, hạn mức và độ nhạy cảm.
Bước 2 — Thiết kế thuộc tính của key. Với mỗi key, xác định: prefix (sk_live_, pk_test_), scope (đọc/ghi/quyền đặc biệt), môi trường (test/live), rate limit, thời hạn (expiry), và phần mô tả (key này của ai, dùng cho việc gì). Đừng quên: key chỉ hiện một lần lúc tạo, sau đó chỉ xem được 4 ký tự cuối.
Bước 3 — Quy trình tạo (create). Người dùng vào dashboard → đặt tên/scope → hệ thống sinh key → hiển thị một lần duy nhất kèm cảnh báo "hãy lưu ngay" → lưu bản hash phía server. Spec cần ghi rõ ai có quyền tạo và có cần duyệt không (key quyền cao thì nên cần duyệt).
Bước 4 — Quy trình xoay vòng (rotate) theo mô hình dual-key. Cho phép một client tồn tại đồng thời tối đa 2 key. Tạo key mới → đối tác cập nhật → theo dõi log để xác nhận key cũ không còn được dùng → revoke key cũ sau grace period (ví dụ 7–30 ngày tùy mức độ).
Bước 5 — Quy trình thu hồi (revoke). Nút "revoke" phải có tác dụng tức thì. Spec cần định nghĩa các điều kiện bắt buộc revoke: nghi ngờ lộ key, đối tác chấm dứt hợp đồng, nhân sự nghỉ việc, phát hiện lưu lượng bất thường.
Bước 6 — Cảnh báo và lịch định kỳ. Gửi email/Telegram nhắc trước khi key hết hạn (ví dụ trước 14 ngày). Đặt chính sách rotate định kỳ (ví dụ 90 ngày một lần). Theo dõi key "ngủ đông" (lâu không dùng) để cân nhắc thu hồi.
Bước 7 — Ghi log và giám sát. Mỗi key gọi gì, lúc nào, từ IP nào — phải log lại. Đây là dữ liệu sống còn khi điều tra sự cố và khi cần biết "có thể revoke key này an toàn chưa".
Lỗi thường gặp & mẹo
- Lưu key gốc trong database. Sai nghiêm trọng. Phải lưu bản hash. Nếu DB bị lộ mà key lưu dạng plaintext thì toàn bộ partner gặp nguy. Mẹo: chỉ lưu hash + 4 ký tự cuối để hiển thị nhận diện.
- Một key dùng cho tất cả. Dùng chung một key cho nhiều mục đích khiến khi cần revoke một chỗ thì sập tất cả. Mẹo: mỗi mục đích/đối tác/môi trường một key riêng.
- Revoke ngay mà không có grace period. Gây downtime cho partner. Mẹo: với key partner, luôn ưu tiên rotate kiểu dual-key; chỉ revoke "không thương tiếc" khi chắc chắn key đã bị lộ và phải chặn gấp.
- Không có ngày hết hạn. Key sống vĩnh viễn là rủi ro tích lũy. Mẹo: đặt expiry mặc định và chính sách rotate định kỳ.
- Nhúng key live vào mobile/web mà không restriction. Như tình huống ĂnLẹ. Mẹo: giới hạn theo app/IP/API + đẩy thao tác nhạy cảm về backend.
- Không tách test/live. Mẹo: prefix rõ ràng và môi trường tách biệt, để không bao giờ test lại đụng vào dữ liệu/tiền thật.
- Quên log và cảnh báo. Khi key hết hạn lúc nửa đêm mà không ai được báo, dịch vụ sập và mất cả tiếng tìm nguyên nhân. Mẹo: luôn có cảnh báo trước hạn và log đầy đủ.
Bài tập thực hành
- Phân loại key: Cho một dự án ví điện tử có: partner cửa hàng tích hợp thanh toán, 10 microservice nội bộ, một app mobile cho người dùng, một public API tra cứu phí giao dịch. Hãy liệt kê các loại key cần có, kèm scope và rate limit đề xuất cho từng loại.
- Viết runbook rotate: Soạn quy trình dual-key rotation cho một partner B2B, gồm các bước, grace period đề xuất, và tiêu chí cụ thể để được phép revoke key cũ. Ghi rõ ai chịu trách nhiệm từng bước.
- Xử lý sự cố lộ key: Một merchant báo key live bị commit nhầm lên GitHub công khai 2 giờ trước. Viết kịch bản xử lý theo thứ tự ưu tiên: việc gì làm ngay, việc gì làm sau, và làm sao để tránh gián đoạn thanh toán của merchant.
- Rà soát spec: Cho một spec API Key chỉ ghi "hệ thống cấp một API Key cho mỗi đối tác, key không hết hạn". Hãy chỉ ra ít nhất 4 điểm yếu và đề xuất cải thiện.
Tóm tắt
API Key là cơ chế "hệ thống nói chuyện với hệ thống", phổ biến cho partner B2B, internal services, public API có rate limit và SDK trên mobile. Khác với token ngắn hạn, key sống lâu nên rủi ro lộ cao hơn, và đó là lý do ta phải quản lý chặt vòng đời của nó.
Ba động từ cốt lõi cần nhớ: Create (tạo, key chỉ hiện một lần, lưu hash chứ không lưu key gốc, gán scope/rate limit/expiry), Rotate (xoay vòng bằng mô hình dual-key có grace period để không downtime), và Revoke (thu hồi tức thì khi lộ key hoặc chấm dứt hợp tác).
Qua ba tình huống — PayBeo cấp key cho merchant, TíchLũy rotate hàng loạt khi sự cố, và ĂnLẹ bị bóc key trong app — bạn thấy rõ: key partner cần grace period, key internal cần runbook rõ ràng, và key client cần restriction cùng kiến trúc đẩy thao tác nhạy cảm về backend. Là một BA, giá trị của bạn nằm ở chỗ viết được spec và quy trình để mỗi chiếc key được tạo đúng, sống an toàn, và "ra đi" mà không làm sập dịch vụ của ai.