Xác thực

~3 phút đọc

Mọi lời gọi tới /v1 mang một khoá API trong header Authorization. Khoá được tạo trong trang Nhà phát triển của tài khoản; mỗi khoá thuộc một tổ chức và chỉ làm được những việc nằm trong scope của nó.

Authorization: Bearer dt_test_…

Hai loại khoá

Tiền tố	Dữ liệu	Dùng khi
`dt_test_`	Dữ liệu thử (sandbox), không tác động tài khoản thật.	Phát triển, kiểm thử tự động, ví dụ trong tài liệu.
`dt_live_`	Dữ liệu thật của tổ chức.	Chạy thật.

Giữ hai khoá ở hai biến môi trường khác nhau và đừng dùng khoá dt_live_ trong mã chạy thử. Ví dụ trong tài liệu luôn đọc khoá từ $DT_API_KEY.

Scope và quyền

Mỗi route ghi quyền cần có (x-dt-permission) và scope của khoá (x-dt-scope) trong đặc tả OpenAPI. Với các route đọc hiện có:

Scope	Cho phép
`accounts:read`	Danh sách và chi tiết tài khoản ngân hàng (che STK 4 số cuối).
`transactions:read`	Danh sách, chi tiết, nguồn gốc, nhật ký, đồng bộ và tổng hợp giao dịch.
`balances:read`	Số dư của một tài khoản hoặc của tất cả tài khoản (tách tạm tính/đã xác thực).
`webhooks:write`	Tạo, sửa endpoint webhook, kiểm thử (`:test`), phát lại (`:replay`), xoay khoá (`:rotate-secret`).
`mcp:read`	Gọi các công cụ MCP chỉ đọc (`/mcp/readonly` hoặc chế độ đọc).
`collect:write`	Tạo yêu cầu thanh toán VietQR và mã đơn DTP.
`reconcile:propose`	Tạo phân bổ đối soát nháp, yêu cầu checker duyệt.
`integrations:read`	Đọc trạng thái và nhật ký các kênh tích hợp thương mại/chat.
`integrations:write`	Quản lý (`integration.manage`), kiểm thử (`integration.test`) và phát lại sự kiện tích hợp (`integration.replay`). Không áp dụng cho xoay credential (luôn cần con người thao tác qua step-up).

"Đã xác thực" trong balances:read là xác thực nguồn, không phải ngân hàng xác nhận quyết toán.

Khoá thiếu scope nhận 403 scope_not_allowed; khoá đủ scope nhưng người cấp không có quyền trên dữ liệu đó nhận 403 permission_denied. Hãy cấp khoá đúng scope tối thiểu bạn cần.

Giữ khoá an toàn

Lưu khoá trong trình quản lý bí mật hoặc biến môi trường của nơi chạy, không đưa vào mã nguồn, ảnh chụp màn hình hay nhật ký.
SDK không bao giờ ghi khoá vào log hay thông điệp lỗi; mã của bạn cũng nên như vậy.
Khoá có thể được giới hạn theo địa chỉ IP: lời gọi từ IP khác nhận 403 ip_not_allowed.
Nghi ngờ lộ khoá: thu hồi ngay trong trang Nhà phát triển. Từ lúc đó mọi lời gọi bằng khoá đó nhận 401 api_key_revoked.

Lỗi xác thực thường gặp

HTTP	Mã lỗi	Thử lại	Ý nghĩa
401	`unauthenticated`	không	Cần đăng nhập
401	`invalid_api_key`	không	Khoá API không hợp lệ
401	`api_key_expired`	không	Khoá API đã hết hạn
401	`api_key_revoked`	không	Khoá API đã bị thu hồi
403	`ip_not_allowed`	không	Địa chỉ IP không được phép với khoá này
403	`permission_denied`	không	Không đủ quyền
403	`scope_not_allowed`	không	Phạm vi khoá không cho phép route này

Cả bảy lỗi đều không nên thử lại nguyên văn: sửa khoá, scope hoặc IP rồi mới gọi lại. Cách đọc phản hồi lỗi ở trang Lỗi.