Bảo mật apiKey khi tích hợp Gigago eSIM API: 5 quy tắc bắt buộc

Trần Vân

|

Đăng: 10/2026

apiKey là mã định danh và thông tin xác thực mà Gigago cấp cho mỗi đối tác để gọi eSIM API. Key có giá trị như mật khẩu. Nếu bị lộ, người khác có thể sử dụng API dưới tài khoản của đối tác, bao gồm tạo đơn và phát sinh chi phí. Vì vậy, ngay từ khi bắt đầu tích hợp, đội kỹ thuật nên áp dụng một số quy tắc.

Tài liệu Gigago eSIM API đặt ra 5 quy tắc an toàn bắt buộc: không đưa apiKey vào code frontend, không commit lên Git, không gửi qua kênh không mã hóa, lưu ở biến môi trường phía server và luôn gọi API qua HTTPS.

Bài viết này giải thích từng quy tắc, cách tách key giữa hai môi trường và cách xử lý khi nghi lộ key, dựa trên trang “Bảo mật & apiKey” trong tài liệu chính thức API docs của Gigago.

apiKey của Gigago là gì và vì sao phải bảo vệ?

apiKey là mã định danh duy nhất Gigago cấp cho mỗi đối tác, được gửi trong header của mọi request tới Gigago eSIM API. Hệ thống dùng apiKey để xác định đối tác, quyền truy cập và hạn mức.

Đặc biệt, API tạo đơn hàng có thể được sử dụng để tạo giao dịch eSIM. Vì vậy, việc để lộ apiKey không chỉ là vấn đề bảo mật thông tin mà còn có thể dẫn đến các giao dịch ngoài ý muốn.

Ví dụ một request lấy danh sách gói cước trên Sandbox, theo tài liệu:

curl -X POST “https://sandbox-partners-api.gigago.com/api/partner/getPackages” \

-H “apiKey: YOUR_API_KEY” \

-H “Content-Type: application/json” \

-d ‘{ “columnFilters”: {}, “page”: 0, “pageSize”: 0 }’

Vì mọi request chỉ cần apiKey để xác thực, ai nắm được key cũng gọi được API dưới tên bạn. Với API Tạo đơn hàng, điều đó có nghĩa là đơn hàng và chi phí thật phát sinh trên tài khoản agency của bạn. Nếu mới tìm hiểu, xem tổng quan cách API vận hành tại bài Gigago eSIM API: tài liệu tích hợp cho đối tác và developer.

apiKey được cấp sẵn khi đối tác có tài khoản agency của Gigago, xem và reset trong phần Profile / API Key.

Nguyên tắc quan trọng: apiKey không nên xuất hiện trong code hoặc dữ liệu mà người dùng cuối có thể truy cập.

→ Xem thêm: Luồng một đơn eSIM qua API

5 quy tắc bảo mật apiKey khi tích hợp Gigago eSIM API

1. Không đưa apiKey vào code frontend

Đây là nguyên tắc quan trọng nhất. Code chạy trên trình duyệt hoặc trong ứng dụng di động có thể bị người dùng cuối xem mã nguồn và trích xuất key. Vì vậy, website hoặc app không nên gọi trực tiếp tới Gigago eSIM API nếu request cần chứa apiKey.

Cách làm đúng: frontend → backend → Gigago API. Website hoặc app gửi yêu cầu tới máy chủ (backend) của đối tác. Backend thêm apiKey vào request, gọi Gigago API, rồi trả kết quả cần thiết về cho giao diện. apiKey không được gửi xuống frontend hoặc đưa vào code mà người dùng cuối có thể truy cập.

Nói ngắn gọn: apiKeyphải được giữ ở phía server, không để lộ cho người dùng cuối.

2. Không commit apiKey lên Git, kể cả repo private

Không đưa apiKey trực tiếp vào source code rồi commit lên Git repository. Một key từng được commit có thể vẫn tồn tại trong lịch sử Git hoặc các bản sao của repository, ngay cả khi đã xóa key khỏi phiên bản code hiện tại.

Repo private không đồng nghĩa với nơi lưu secret: repo vẫn có thể bị chia sẻ, sao chép hoặc lộ quyền truy cập.

Cách làm đúng: đặt apiKey trong file .env và thêm file này vào .gitignore, như tài liệu hướng dẫn. Nếu lỡ commit key, cách xử lý an toàn là:

1. Reset/revoke key cũ.
2. Lấy apiKey mới
3. Cập nhật key mới trong biến môi trường hoặc hệ thống quản lý secret.

Phần xử lý khi key bị lộ được hướng dẫn cụ thể ở cuối bài.

3. Không gửi apiKey qua chat hoặc email không mã hóa

Không nên gửi apiKey trực tiếp qua các kênh chat hoặc email thông thường để nhờ developer cấu hình. Tin nhắn và email có thể được chuyển tiếp, lưu trữ lâu dài hoặc bị truy cập trái phép. Gửi key qua các kênh này làm tăng số nơi key có thể bị lộ.

Cách làm đúng: Với team phát triển, nên dùng trình quản lý secret để chia sẻ và lưu key. Tùy hạ tầng, doanh nghiệp có thể sử dụng secret manager thay vì chia sẻ key trực tiếp giữa các thành viên. Tài liệu Gigago nêu ví dụ như Vault, 1Password hoặc AWS Secrets Manager.

Điểm quan trọng là developer cần được cấp quyền sử dụng secret mà không nhất thiết phải nhìn thấy hoặc copy key thủ công.

4. Lưu apiKey ở server bằng biến môi trường hoặc secret manager

apiKey nên được lưu ở phía backend, thay vì viết trực tiếp trong source code. Thay vì viết thẳng key vào code, máy chủ đọc key từ biến môi trường hoặc trình quản lý secret khi chạy. Mọi lời gọi tới Gigago API đều đi từ backend của đối tác.

Ví dụ minh họa (Node.js), key được đọc từ biến môi trường thay vì viết trong code:

// .env (không commit lên Git)// GIGAGO_API_KEY=your_api_key_here
const apiKey = process.env.GIGAGO_API_KEY;

Ví dụ trên là cách làm phổ biến, không phải code mẫu trong tài liệu Gigago. Đội kỹ thuật áp dụng tương tự với ngôn ngữ đang dùng.
File .env phù hợp cho môi trường local hoặc development. Với Production, nên dùng trình quản lý secret hoặc cơ chế quản lý secret phù hợp với hạ tầng triển khai.

5. Chỉ gửi apiKey qua HTTPS

apiKey được gửi trong header của request, vì vậy kết nối tới Gigago API phải dùng HTTPS để bảo vệ dữ liệu trên đường truyền. base_url của Gigago trong tài liệu đều dùng https://.

HTTPS giúp mã hóa dữ liệu trong quá trình truyền giữa hệ thống của đối tác và API server. Khi xây dựng backend gọi Gigago API, hãy đảm bảo endpoint sử dụng HTTPS thay vì HTTP.

Lưu ý: HTTPS bảo vệ key trong quá trình truyền nhưng không thay thế cho việc lưu trữ apiKey an toàn ở phía server.

Sandbox và Production: cần tách apiKey như thế nào?

Gigago tách riêng apiKey cho từng môi trường phục vụ cho các mục đích khác nhau. Key Sandbox và key Production hoàn toàn tách biệt, không dùng chung một key cho hai môi trường.

Key Production cần được bảo vệ chặt chẽ nhất, vì đây là key gắn với giao dịch và chi phí thật. Khi chuyển sang Production, đối tác dùng base_url và apiKey của môi trường Production được Gigago cung cấp khi đăng ký làm đại lý.

→ Nếu cần xem lại toàn bộ quy trình từ chuẩn bị, test Sandbox đến chuyển Production, có thể xem bài: Checklist tích hợp Gigago eSIM API

3 bước cần làm nếu apiKey bị lộ

Nếu apiKey đã xuất hiện trong Git, chat, email hoặc bất kỳ nơi nào người không có quyền có thể truy cập, hãy coi key là đã bị lộ và reset key, thay vì chỉ xóa key khỏi nơi đã đăng.

Tài liệu Gigago hướng dẫn làm ngay 3 bước:

Bước 1: Reset apiKey

Vào Profile → API Key để reset key.

Sau khi reset, key cũ không còn được sử dụng.

Bước 2: Cập nhật key mới

Thay key mới trong:

• Environment variables
• Secret manager
• Backend configuration
• Các hệ thống hoặc server đang sử dụng key cũ

Không cần đưa key mới vào source code.

Bước 3: Kiểm tra các đơn hàng

Sau khi thay key, nên kiểm tra lại lịch sử đơn hàng của agency để phát hiện những giao dịch bất thường nếu có.

Nếu cần liên hệ Gigago để hỗ trợ, nên cung cấp thông tin giúp đội kỹ thuật xác định request, chẳng hạn:

• Môi trường đang sử dụng: Sandbox hoặc Production
• request_id
• Thời điểm gọi API

Không gửi trực tiếp apiKey vào nội dung yêu cầu hỗ trợ.

Nếu cần đội kỹ thuật Gigago hỗ trợ, hãy gửi kèm môi trường (DEV hoặc PROD), request_id liên quan và thời gian gọi API.

Checklist bảo mật apiKey cho developer

Trước khi đưa hệ thống lên Production, có thể kiểm tra nhanh:

1. apiKey chỉ được sử dụng ở backend
2. Không có apiKey trong frontend/source code hiển thị cho người dùng
3. Không commit apiKey vào Git
4. File .env chứa secret không được commit
5. Production sử dụng cơ chế quản lý secret phù hợp
6. Không gửi key qua chat/email không được bảo mật
7. API request sử dụng HTTPS
8. Sandbox và Production sử dụng key riêng
9. Đã biết cách reset key nếu xảy ra sự cố

Câu hỏi thường gặp