Zenith | Xác thực

Header credential

Gửi đủ 2 header trong mọi request. Secret được so khớp phía server bằng bcrypt — Zenith không lưu plain text.

Header	Vai trò
`X-Access-Key-ID`	Định danh public của partner key.
`X-Access-Key-Secret`	Shared secret đi kèm key id.

Quá 10 lần xác thực sai trên một key id trong 60 giây trả về 429 too_many_requests. Chỉ giữ credential phía server; nếu lộ thì xin Zenith rotate.

API scope

Key được bật theo từng scope. Gọi ngoài scope được cấp trả 403; key bị tắt trả 401. Muốn đổi scope liên hệ Zenith operations.

Scope	Mở khóa
`users`	Tạo partner user và submit KYC.
`transfers`	Transfer onramp/offramp, tỷ giá, lịch sử, hạn mức ngày.
`domestic_virtual_account`	Virtual account, VA transfer, rút ngân hàng.
`webhook`	`PUT /partners/update-webhook`.

Tác động lên user — userId

Endpoint theo user nhận userId qua query hoặc JSON body — là external user id của bạn khai báo lúc tạo user, không phải id nội bộ Zenith. API tự map sang partner user tương ứng.

userId qua query

GET /api/v2/partners/users?userId=ext-user-001

userId qua body

POST /api/v2/partners/users/kyc
{ "userId": "ext-user-001", "nationalId": "...", ... }

userId không tồn tại dưới partner của bạn → 401 Partner user not found.
Thiếu userId → 401 missing user id.
Endpoint virtual-account yêu cầu thêm KYC của user ở trạng thái APPROVED — nếu không trả 403.

Checklist

Luôn HTTPS, luôn server-to-server — không đưa secret vào browser hay mobile app.
Key id + secret là một cặp; chỉ gửi một sẽ nhận 401 missing access keys.
Giữ userId ổn định theo user để KYC, ví và transfer cùng gắn một identity.