Beta · Đặc tả có thể còn thay đổi trước khi ra mắt chính thức. Tên miền API api.hensa.example là tạm thời. Xem thay đổi →

Xác thực & khóa API

Mọi request gửi khóa API trong header Authorization:

Authorization: Bearer hk_live_9fK2…7Kp2

Hai loại khóa

Khóa	Dùng cho	Tiền thật?
`hk_test_…`	Phát triển, CI, demo. Dùng được mô phỏng tiền về.	Không – dữ liệu tách biệt hoàn toàn
`hk_live_…`	Production	Có

Tiền tố rõ ràng giúp bạn (và công cụ quét bí mật của GitHub) nhận ra ngay khi khóa bị lộ.

Tạo và quản lý khóa

Dashboard › Cài đặt › Developer › Khóa API. Tạo khóa cần xác thực 2 lớp. Khóa chỉ hiển thị một lần – Hensa chỉ lưu bản băm, không ai (kể cả Hensa) xem lại được.

Mỗi khóa hiển thị “dùng lần cuối” – khóa lâu không dùng nên thu hồi.

Bảo vệ khóa

Chỉ đặt khóa ở máy chủ (biến môi trường / secret manager). Không đặt trong code trình duyệt, app di động, repo Git.
Mỗi hệ thống một khóa (website, app, phần mềm kế toán…) – lộ một khóa chỉ cần thu hồi khóa đó.
Nghi lộ khóa: tạo khóa mới → triển khai → thu hồi khóa cũ. Thu hồi có hiệu lực ngay.

Lỗi xác thực

HTTP	`code`	Nguyên nhân
401	`unauthorized`	Thiếu header, sai khóa, hoặc khóa đã thu hồi
403	`forbidden`	Khóa không có quyền cho thao tác này
403	`test_mode_only`	Gọi endpoint chỉ dành cho test bằng khóa `hk_live_`