# API key

Tạo khoá để phần mềm của lập trình viên dùng Hạ Tầng, chỉ cấp cho mỗi khoá đúng quyền nó cần, và thu hồi ngay khoá bị lộ.

API key cho phép phần mềm dùng Hạ Tầng nhân danh doanh nghiệp của bạn: website gửi email xác nhận đơn, hệ thống bán hàng đọc hội thoại, máy chủ của bạn tạo yêu cầu thanh toán. Mỗi khoá là một chuỗi bí mật dài mà phần mềm gửi kèm mọi yêu cầu.

Thường bạn tạo khoá cho lập trình viên. Bạn không cần hiểu API, nhưng bạn quyết định mỗi khoá được làm gì, và dừng được bất kỳ khoá nào ngay lập tức.

Để quản lý khoá, bạn cần quyền **Developer (API key, webhook)**, chủ sở hữu và quản trị viên luôn có quyền này.

## Tạo khoá

1. Mở **Cài đặt → API Keys** (trang này cũng có trong ứng dụng Email, ở **Email → API Keys**).
2. Bấm **Tạo key**.
3. Đặt tên cho biết khoá dùng ở đâu, ví dụ "Website production" hay "Phần mềm bán hàng". Hộp thoại nhắc rằng khoá chỉ dùng được cho doanh nghiệp này.
4. Ở mục **Key này có thể làm gì**, chỉ đánh dấu những gì phần mềm cần (xem bên dưới).
5. Với khoá gửi email, bạn có thể giới hạn chỉ gửi từ một **Tên miền gửi**. Nếu không, để **Tất cả tên miền**.
6. Ở **Key này chạy ở đâu?**, giữ **Trên server của bạn** cho gần như mọi trường hợp: gửi email, phần mềm bán hàng, plugin, cron. Chỉ chọn **Trong trình duyệt** khi lập trình viên báo khoá sẽ nằm trong JavaScript của trang web; khi đó nhập các địa chỉ website được dùng khoá, mỗi dòng một địa chỉ, dạng `https://shop.vn`. Khoá chạy trong trình duyệt bị chặn khi gọi từ server.
7. Bấm **Tạo key**.

![Tạo API key và chọn khoá được làm gì](https://hatang.dev/help/img/vi/integrations/new-key.webp)

Khoá hiện ra một lần duy nhất, dưới tiêu đề **Đã tạo key**. Bấm nút sao chép và gửi cho lập trình viên qua kênh an toàn (trình quản lý mật khẩu, không phải nhóm chat). Bấm **Xong**. Hạ Tầng không bao giờ hiện lại toàn bộ khoá; nếu mất, hãy tạo khoá mới và thu hồi khoá cũ.

## Khoá được làm gì

Mỗi ứng dụng đang bật có các quyền riêng. Khoá cần ít nhất một quyền.

| Ứng dụng | Quyền | Cho phép |
|---|---|---|
| Email | **Gửi** | Gửi email qua API và qua SMTP relay |
| Email | **Đọc** | Liệt kê và đọc email, tên miền, liên hệ |
| Email | **Quản lý** | Tên miền, webhook, danh sách nhận, chiến dịch email |
| Hỗ trợ khách hàng | **Đọc** | Hội thoại, tin nhắn, khách truy cập |
| Hỗ trợ khách hàng | **Ghi** | Trả lời, giao việc, xử lý xong, quản lý site |
| Thanh toán | **Đọc** | Khoản thanh toán, giao dịch, hoá đơn điện tử |
| Thanh toán | **Ghi** | Tạo thanh toán, liên kết ngân hàng, phát hành hoá đơn điện tử |
| Sản phẩm | **Đọc** | Sản phẩm, danh mục, đơn hàng |
| Sản phẩm | **Ghi** | Tạo, sửa, nhập sản phẩm; tạo đơn hàng và link thanh toán |
| Khách hàng | **Đọc** | Khách hàng, trường tuỳ chỉnh, xuất CSV, lịch sử ZNS |
| Khách hàng | **Ghi** | Sửa và gộp khách hàng, trường tuỳ chỉnh, gửi ZNS |
| Blog | **Đọc** | Bài viết, chuyên mục, ảnh, API nội dung |
| Blog | **Ghi** | Viết, xuất bản bài viết, tải ảnh |

Quyền **Ghi** bao gồm **Đọc**. Các khoá tạo trước khi Sản phẩm và Khách hàng có quyền riêng vẫn dùng được ở đó nhờ quyền Hỗ trợ khách hàng; với khoá mới, hãy đánh dấu thẳng Sản phẩm hoặc Khách hàng. Mỗi phần mềm nên có khoá riêng với ít quyền nhất có thể: khoá chỉ để gửi email xác nhận đơn thì chỉ cần **Gửi** của Email.

Khoá có quyền **Gửi** cũng dùng làm mật khẩu cho SMTP relay, với tên đăng nhập `hatang`. Xem [SMTP relay](https://hatang.dev/vi/help/email/smtp-relay).

## Danh sách khoá

![Các API key của doanh nghiệp, chỉ hiện phần đầu của mỗi khoá](https://hatang.dev/help/img/vi/integrations/api-keys.webp)

Mỗi khoá hiện **Tên**, vài ký tự đầu của **Token** (đủ để nhận ra, không bao giờ là cả khoá), **Có thể làm** gì (**toàn quyền** với các khoá cũ được làm mọi thứ), **Dùng lần cuối** và ngày tạo. Khoá chạy trong trình duyệt có thêm dòng **chỉ từ trình duyệt** kèm các địa chỉ website của nó.

Nếu phần mềm báo `restricted_api_key` kèm câu *only accepts browser requests*, khoá đó đang bị giới hạn theo trình duyệt mà lại được dùng từ server. Tạo khoá mới với **Trên server của bạn**, thay vào phần mềm, rồi thu hồi khoá cũ.

Khoá tạo ở đây là khoá chính thức: bắt đầu bằng `ht_` và tác động lên dữ liệu thật. Khoá bắt đầu bằng `ht_test_` là khoá thử nghiệm, chỉ dùng được với môi trường thử nghiệm của Thanh toán.

## Thu hồi khoá

Bấm **Thu hồi** cạnh một khoá. Khoá ngừng hoạt động ngay và biến khỏi danh sách: phần mềm nào còn dùng nó sẽ nhận lỗi. Hãy thu hồi khi:

- người hoặc công ty giữ khoá không còn làm việc với bạn,
- khoá có thể đã bị lộ (dán vào nhóm chat, đưa lên mã nguồn, gửi qua email),
- phần mềm dùng khoá không còn hoạt động.

Để thay khoá mà không gián đoạn: tạo khoá mới trước, để lập trình viên chuyển sang, kiểm tra **Dùng lần cuối** của khoá cũ không còn thay đổi, rồi mới thu hồi khoá cũ.

## Giữ khoá an toàn

- Khoá hành động nhân danh doanh nghiệp. Ai có khoá đều làm được những gì quyền của khoá cho phép, không cần đăng nhập.
- Không bao giờ đặt khoá trong mã công khai của website, trừ khi lập trình viên đã đặt **Origin trình duyệt** cho khoá và khoá chỉ có những quyền trình duyệt cần.
- Thỉnh thoảng xem **Dùng lần cuối**. Khoá nhiều tháng không ai dùng thường có thể thu hồi.

Dành cho lập trình viên: xác thực, mã lỗi và giới hạn tốc độ có trong [tài liệu cho lập trình viên](https://hatang.dev/vi/docs/guides/getting-started/authentication).