Xác thực

Mọi request tới API v1 phải có API key của bạn trong header Authorization. Khóa có toàn quyền trên dữ liệu tài khoản của bạn, nên chỉ dùng từ backend.

Tạo khóa ở trang API key trong app. Khóa có dạng boa_live_ theo sau là 36 ký tự chữ và số (khóa sandbox là boa_test_). 6 ký tự cuối là checksum: khóa gõ sai hay cắt thiếu bị từ chối ngay, và công cụ quét secret nhận ra khóa bị lộ mà không báo nhầm. Khóa tạo trước 05/11/2026 có 40 ký tự, vẫn dùng bình thường. Gửi khóa theo kiểu Bearer:

Header

Authorization: Bearer boa_live_...

GET /v1/account

curl https://app.bankopenapi.com/api/v1/account \
  -H "Authorization: Bearer $BANKOPENAPI_API_KEY"

const res = await fetch("https://app.bankopenapi.com/api/v1/account", {
  headers: {
    Authorization: `Bearer ${process.env.BANKOPENAPI_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);

<?php
$ch = curl_init('https://app.bankopenapi.com/api/v1/account');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BANKOPENAPI_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status >= 400) {
    throw new Exception($data['error']['code'] . ': ' . $data['error']['message']);
}
print_r($data);

import os
import requests

res = requests.get(
    "https://app.bankopenapi.com/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['BANKOPENAPI_API_KEY']}"},
    timeout=15,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)

GET /v1/account trả thông tin chủ khóa, dùng để kiểm tra khóa còn chạy. Xem API tài khoản.

Lỗi xác thực

Thiếu header, khóa sai định dạng, khóa không tồn tại, đã thu hồi hoặc đã hết hạn đều trả HTTP 401 với mã INVALID_API_KEY và header WWW-Authenticate: Bearer. Câu trong message nói rõ lý do:

401: thiếu header

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Thiếu API key. Gửi kèm header \"Authorization: Bearer <API key>\"."
  }
}

401: khóa đã thu hồi

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key này đã bị thu hồi. Tạo khóa mới tại https://app.bankopenapi.com/api-key rồi thay vào hệ thống của bạn."
  }
}

Một địa chỉ IP xác thực sai quá 100 lần trong một phút thì bị chặn tạm thời với mã 429 RATE_LIMITED, để chống dò khóa. Đợi một phút rồi thử lại với khóa đúng.

Giữ bí mật API key

Chỉ gọi API từ backend. API không bật CORS: request từ trình duyệt bị chặn ngay ở bước preflight. Đừng đặt khóa trong JavaScript của trang web, app di động hay extension.
Lưu khóa trong biến môi trường hoặc trình quản lý secret của nền tảng bạn dùng. Không commit khóa lên Git, kể cả repo riêng tư.
BankOpenAPI chỉ lưu bản băm (SHA-256) của khóa, nên khóa đầy đủ chỉ hiện một lần lúc tạo. Mất khóa thì tạo khóa mới, chúng tôi không xem lại được.
Mỗi môi trường (production, staging, máy dev) và mỗi AI agent nên dùng một khóa riêng, để thu hồi độc lập.
Response của API có header Cache-Control: no-store: đừng tự cache response chứa dữ liệu tài khoản ở proxy dùng chung.

Tạo, đổi, thu hồi

Mỗi tài khoản có tối đa 10 API key đang hoạt động. Tên khóa dài 1 đến 60 ký tự, đổi được bất cứ lúc nào.
Trang API key hiện tiền tố, 4 ký tự cuối, hạn dùng, lần dùng gần nhất và IP của lần đó (cập nhật tối đa mỗi phút một lần), đủ để nhận ra khóa nào đang được dùng và dùng từ đâu.
Quyền: khóa toàn quyền gọi được mọi endpoint; khóa chỉ đọc chỉ gọi được GETvà các tool chỉ đọc của MCP, lệnh ghi bị trả 403 INSUFFICIENT_PERMISSION. Dùng khóa chỉ đọc cho báo cáo và AI agent.
Hạn dùng: 30, 90 (mặc định), 180 ngày, 1 năm hoặc không hết hạn. Khóa hết hạn bị trả 401 INVALID_API_KEY.
Giới hạn IP: khai báo tối đa 20 địa chỉ IPv4, IPv6 hoặc dải CIDR (vd. 203.0.113.0/24,2001:db8::/64) được gọi bằng khóa, khi tạo khóa hoặc sau đó qua mục "Giới hạn IP" của khóa. Request từ IP khác bị trả403 IP_NOT_ALLOWED, message có IP mà BankOpenAPI nhìn thấy. Để trống là gọi được từ mọi IP. Roll khóa giữ nguyên danh sách. Hệ thống có IPv6 thường gọi ra bằng IPv6, nên khai báo cả địa chỉ IPv6. Không bật cho hệ thống không có IP cố định (serverless, Cloudflare Workers).
Mỗi lần tạo hoặc roll khóa, BankOpenAPI gửi email báo chủ tài khoản.

Đổi khóa định kỳ, khi sắp hết hạn hoặc khi người giữ khóa nghỉ việc: bấm Roll API key. BankOpenAPI tạo khóa mới cùng tên, quyền và thời hạn; khóa cũ chạy thêm 1 giờ, 24 giờ (mặc định) hoặc 7 ngày rồi hết hạn, đủ để bạn:

Thay khóa mới vào hệ thống của bạn và deploy.
Trên trang API key, kiểm tra "lần dùng gần nhất" của khóa cũ không còn tăng.

Khóa bị lộ thì roll với tùy chọn "Ngay lập tức": khóa cũ bị thu hồi ngay.

Base URL hiện tại: https://app.bankopenapi.com/api/v1. Giới hạn số request của mỗi khóa ở trang Giới hạn tần suất.

Gửi API key

Lỗi xác thực

Giữ bí mật API key

Tạo, đổi, thu hồi

Bắt đầu với BankOpenAPI