Chỉ tên header X-API-Key được chấp nhận (viết hoa thường tuỳ ý — HTTP không phân biệt). Alias cũ apikeyđã bị bỏ: gửi bằng tên đó thì request bị coi như không có API Key và sẽ nhận 401 từ tầng xác thực JWT, chứ không phải lỗi API Key.
API Key được cấp khi onboard tổ chức và chỉ hiển thị 1 lần. Lưu trong biến môi trường hoặc secret manager, không commit vào source code.
Khi bạn muốn nhúng giao diện econtractid (iframe trên web hoặc SDK mobile), người dùng cuối cần một access token. Backend của bạn dùng API Key để đổi lấy token cho một người dùng cụ thể:
POST https://api.econtractid.com/api/auth/partner-loginx-api-key: econtract_a1b2c3d4...Content-Type: application/json{ "username": "john.doe", "tenantCode": "ACME"}
userInfo ở trên là bản rút gọn. Response thật còn có address, avatar, memberOf, updatedAt, và các trường chữ ký (defaultSignature, imageSignatures, backgroundSignatures).status là số (1 = chờ kích hoạt, 2 = đang hoạt động). organizationId bằng -1 với người dùng bên ngoài — đây là giá trị bình thường, không phải lỗi.
Response không trả về refreshToken và không trả về expiresIn. Xem mục Vòng đời token bên dưới.Lưu ý statusCode trong body luôn là 200 kể cả khi HTTP status là 201 — hãy dựa vào HTTP status thật của response, không dựa vào trường này.
Endpoint này không tạo người dùng. Username chưa tồn tại → trả 404. Người ký phải được onboard trước qua luồng tạo hồ sơ thông thường (khai báo trong signers[] khi gọi POST /documents).Endpoint chỉ cấp token cho người dùng là thành viên của tổ chức tương ứng — cả người ký bên ngoài (external) lẫn nhân sự nội bộ (internal). Tài khoản quản trị hệ thống (super admin) bị từ chối (403), vì token này được cấp không qua mật khẩu.
Token cấp qua partner-loginkhông cần mật khẩu. Ai giữ API Key đều có thể lấy token của bất kỳ người dùng external nào trong tổ chức. API Key tuyệt đối không được để lộ xuống trình duyệt hoặc ứng dụng di động — chỉ gọi từ backend.
Không dùng Authorization: Bearer <token>. Hệ thống chỉ đọc token từ header x-access-token, và không có tiền tố Bearer. Gửi sai tên header — hoặc thêm tiền tố Bearer — thì request bị coi như không có token và trả 401 mà không kèm mô tả.
Các endpoint Integration API nhận cả hai cách xác thực: X-API-Key (người dùng = tài khoản gắn với key) hoặc x-access-token (người dùng = chủ sở hữu token). Gửi kèm cả hai thì API Key được ưu tiên, token bị bỏ qua — nên chỉ gửi một.
Phải là x-access-token. Authorization: Bearer ... → luôn 401
Tiền tố
Gửi JWT thuần, không có Bearer phía trước
Khoảng trắng
Token bị xuống dòng / thêm dấu cách khi copy làm hỏng chữ ký
Đúng môi trường
Token lấy ở môi trường dev không dùng được trên production và ngược lại — khoá ký khác nhau
Hạn dùng
Giải mã phần payload, so exp (epoch giây) với hiện tại
Nguyên vẹn
Token gồm đúng 3 đoạn ngăn bởi dấu .; thiếu hoặc thừa một ký tự là chữ ký sai
Proxy trung gian
Một số CDN/API gateway lọc bỏ header lạ — kiểm tra bằng cách gọi thẳng API, không qua proxy
Tầng xác thực chỉ kiểm tra chữ ký và hạn dùng của token, không kiểm tra quyền. Nhận 401 nghĩa là token/header sai — vấn đề về quyền hạn trả 403, còn dữ liệu không thuộc phạm vi người dùng trả 404.
