Bắt đầu

Xác thực

API B2B dùng API key trong header x-api-key. Portal dùng session cookie riêng; hai cơ chế không thay thế nhau.

Header

http

curl "https://api.kovitel.com/api/v1/pool/status" \
  -H "x-api-key: kov_live_…"

API key được lưu thế nào?

KOVITEL chỉ lưu hash SHA-256 của API key kèm pepper. Raw key chỉ hiển thị một lần khi tạo tài khoản hoặc rotate. Nếu mất key, bạn phải rotate key mới — không thể khôi phục key cũ.

Trạng thái tài khoản

PENDING: đã đăng nhập portal nhưng API key chưa có hiệu lực; các endpoint nghiệp vụ trả 403 ACCOUNT_PENDING.
ACTIVE: key hoạt động, có thể allocate và đổi trạng thái eSIM.
SUSPENDED: key bị vô hiệu hóa; liên hệ KOVITEL để mở lại.

Rate limit

Mỗi partner có giới hạn request theo hợp đồng. Worker giới hạn 5 request/giây tới cổng Viettel để bảo vệ mạng lõi. Khi vượt giới hạn API, hệ thống trả 429 kèm header rate limit.

Cách ly dữ liệu

Mọi truy vấn đều gắn với client của API key. ICCID của partner khác trả 404, không tiết lộ sự tồn tại của tài nguyên.

Rotate key

Vào API keys trên portal để rotate. Key cũ bị vô hiệu hóa ngay lập tức; cập nhật biến môi trường trước khi gọi request tiếp theo.

Lỗi xác thực

401 Unauthorized

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing x-api-key or partner session",
    "requestId": "2f2ffb6a-…"
  }
}

Không đưa API key vào mã frontend, mobile app hoặc repository công khai. Nếu key bị lộ, rotate ngay và kiểm tra audit log.