Xác thực
Toàn bộ cách xác thực API HiTechCloud: khoá API, Bearer token, token cá nhân, OAuth2 / OpenID Connect, service account (client credentials) và ký HMAC cho webhook — kèm ví dụ cURL, Node.js và PHP.
Mọi API của HiTechCloud chỉ chạy trên HTTPS. Tuỳ sản phẩm, bạn dùng một trong các phương thức dưới đây. Trang Tổng quan của mỗi sản phẩm nêu rõ phương thức áp dụng; trang này là bản tham chiếu chung.
Chọn phương thức phù hợp
- Khoá API —
X-API-Key: <key>— API Tools (tra cứu dữ liệu từ máy chủ). Xem Khoá API. - Bearer token —
Authorization: Bearer <token>— Pay API, Hoá đơn điện tử, Loa thông báo, User API. Xem Bearer token. - Token cá nhân —
Authorization: Bearer hc_pat_…— script / tích hợp nhanh thay cho tài khoản của bạn. Xem Token cá nhân. - OAuth2 / OIDC — Authorization Code + PKCE — đăng nhập người dùng cuối, gọi API thay khách. Xem OAuth2 / OIDC.
- Service account —
grant_type=client_credentials— giao tiếp máy-máy giữa backend của bạn và HiTechCloud. Xem Service account. - Ký HMAC —
X-Signature: <hmac_sha256>— xác minh webhook / IPN HiTechCloud gửi về bạn. Xem HMAC webhook.
Khoá API
Dùng cho API Tools (tra cứu doanh nghiệp, tên miền, mạng, DNS…). Tạo khoá trong Developer Console → Khoá API, rồi gửi qua header X-API-Key tới https://api-tools.hitechcloud.vn. Khoá gắn với phạm vi endpoint và giới hạn tần suất của gói.
curl -s "https://api-tools.hitechcloud.vn/api/v1/portal/lookup/tools/tra-cuu-ma-so-thue" \
-H "X-API-Key: $HTC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"0101243150"}'const res = await fetch(
"https://api-tools.hitechcloud.vn/api/v1/portal/lookup/tools/tra-cuu-ma-so-thue",
{
method: "POST",
headers: {
"X-API-Key": process.env.HTC_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ q: "0101243150" }),
},
);
const data = await res.json();Bearer token
Pay API, Hoá đơn điện tử, Loa thông báo và User API dùng access token gửi qua Authorization: Bearer <token>. Mỗi sản phẩm nêu cách cấp token (khoá merchant, đăng nhập, hoặc OAuth2). Luôn gửi Accept: application/json.
curl -s "https://pay.hitechcloud.vn/api/v1/..." \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Accept: application/json"<?php
$ch = curl_init("https://pay.hitechcloud.vn/api/v1/...");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("ACCESS_TOKEN"),
"Accept: application/json",
],
]);
$body = curl_exec($ch);
$data = json_decode($body, true);Token cá nhân (Personal Access Token)
Token cá nhân cho phép script/công cụ gọi API thay cho tài khoản của bạn mà không cần luồng OAuth đầy đủ. Tạo trong Developer Console hoặc trang tài khoản HiTechCloud ID; token có tiền tố hc_pat_, gắn phạm vi (scope) và hạn dùng. Gửi như một Bearer token thông thường.
OAuth2 / OpenID Connect — HiTechCloud ID
HiTechCloud ID là nhà cung cấp danh tính (IdP) OAuth2 / OIDC dùng chung cho toàn hệ sinh thái: đăng nhập một lần (SSO), passkey, và cấp token để ứng dụng gọi API thay mặt người dùng. Luồng khuyến nghị là Authorization Code + PKCE.
Mọi cấu hình đều lấy được từ tài liệu Discovery (OIDC):
curl -s https://iam.hitechcloud.vn/api/v1/sso/oauth2/.well-known/openid-configuration- Uỷ quyền —
GET /api/v1/sso/oauth2/authorize - Cấp / làm mới token —
POST /api/v1/sso/oauth2/token - UserInfo —
GET /api/v1/sso/oauth2/userinfo - JWKS —
GET /api/v1/sso/oauth2/.well-known/jwks.json - Thu hồi / Introspect —
POST /api/v1/sso/oauth2/revoke·/introspect - Đăng ký ứng dụng (RFC 7591) —
POST /api/v1/sso/oauth2/register - Thiết bị / CLI (RFC 8628) —
POST /api/v1/sso/oauth2/device_authorization
Xem hướng dẫn đầy đủ (PKCE, id_token, device flow, gọi API qua gateway) tại HiTechCloud ID (OAuth2 / OIDC) và đặc tả máy đọc tại API gốc (OpenAPI).
Service account (client credentials)
Service account là danh tính máy-máy cho backend của bạn (không gắn người dùng). Tạo trong trang tài khoản → Service Accounts; khoá có dạng sa_<key_id>.<secret> và chỉ hiện đầy đủ một lần. Có hai cách dùng:
- Client credentials: đổi khoá lấy access token có phạm vi, rồi gọi API bằng Bearer token đó.
- Khoá trực tiếp: với các endpoint hỗ trợ, gửi thẳng khoá service account theo chuẩn của endpoint.
curl -s -X POST https://iam.hitechcloud.vn/api/v1/sso/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=sa_XXXX" \
-d "client_secret=YYYY" \
-d "scope=service"Ký HMAC — xác minh webhook
Khi HiTechCloud gọi ngược (webhook / IPN) về URL của bạn, mỗi yêu cầu kèm chữ ký HMAC-SHA256 trên thân thô (raw body) bằng secret của endpoint, đặt ở header X-Signature. Hãy tính lại chữ ký và so sánh theo thời-gian-hằng (constant-time) trước khi xử lý.
import crypto from "node:crypto";
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody, "utf8")
.digest("hex");
const a = Buffer.from(signature);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Chi tiết theo sản phẩm: Pay — Webhooks.