Xác thực & quyền
Mọi yêu cầu cần một API key trong header Authorization, dùng kiểu Bearer. Không cookie, không OAuth — chỉ cần đúng key là đủ.
- Không tự hết hạn. Key dùng được tới khi quản trị viên thu hồi.
- Chỉ đọc. Key này không sửa hay xoá được dữ liệu.
- Theo quyền. Mỗi key chỉ đọc những loại dữ liệu mà quản trị viên đã chọn khi tạo key (bảng dưới).
- Theo từng phòng khám. Mỗi key chỉ thấy dữ liệu của phòng khám đã tạo ra nó; tối đa 10 key hoạt động cùng lúc mỗi phòng khám.
- Chỉ lưu dấu vân tay. iClinic chỉ giữ giá trị băm sha256 của key nên không xem lại được — mất key thì tạo key mới, không khôi phục được key cũ.
Giữ key như mật khẩu. Đặt trong biến môi trường hoặc kho bí mật, đừng đưa vào mã nguồn hay mã chạy ở trình duyệt của khách hàng. Nghi ngờ lộ key: tạo key mới, cập nhật hệ thống của bạn rồi Thu hồi key cũ — có hiệu lực ngay lập tức.
Quyền (scope)
Quản trị viên chọn quyền khi tạo key; không có ô nào được chọn sẵn. Gọi một đường dẫn mà key không có quyền trả 403 INSUFFICIENT_SCOPE, và câu trả lời giống hệt nhau dù bản ghi có tồn tại hay không.
| Quyền | Đọc được |
|---|---|
encounters:read | /encounters |
patients:read | /patients, /patients/{id} |
appointments:read | /appointments, /appointments/{id} |
receipts:read | /receipts, /receipts/{id} |
therapy:read | /therapy-plans, /therapy-plans/{id} |
Key tạo trước phiên bản 1.1.0 chỉ có encounters:read, đúng như trước đây.
Chỉ xin quyền thật sự cần. Bệnh nhân, lịch hẹn, hóa đơn và liệu trình là dữ liệu cá nhân, một phần là dữ liệu sức khỏe. Hãy dùng chúng đúng mục đích mà bệnh nhân đã đồng ý, và thu hồi key khi không còn dùng.
Đổi key không làm gián đoạn dịch vụ
Tạo key mới → cập nhật hệ thống của bạn → thu hồi key cũ. Trong lúc chuyển, cả hai key vẫn hoạt động song song.
Authorization: Bearer ick_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx