# Lấy khóa API, kết nối và kiểm tra kết nối

> Tạo khóa API (psk_…) trong Dashboard PenAI, gắn khóa vào phần mềm của bạn và chạy một lệnh thử để chắc chắn kết nối đã thông.

Áp dụng cho mọi bản PenAI · Cập nhật 06/10/2026 · Nguồn: https://help.penai.vn/khoa-api/

## Khóa API là gì

Khóa API (API key) là một chuỗi bí mật dạng `psk_…` để **phần mềm** gọi vào PenAI: CRM, website, script, n8n, Make… Mỗi lệnh gọi kèm khóa này để PenAI biết ai đang gọi và được phép làm gì.

Khóa API chỉ dành cho máy gọi máy. Người dùng thì đăng nhập Dashboard bằng email + mật khẩu (tạo ở mục **Người dùng**), không dùng khóa này.

## 1. Tạo khóa API

Cần tài khoản có quyền **Quản trị** — tài khoản khác không thấy mục này.

![Trang Khóa API (tích hợp) trong Dashboard PenAI, đánh số 4 bước tạo khóa](https://help.penai.vn/assets/img/khoa-api-tao-key.svg)

1. Đăng nhập Dashboard, ở menu bên trái (nhóm **Cấu hình**) chọn **🔑 Khóa API (tích hợp)**.
2. Ô **Tên key**: đặt tên theo nơi sẽ dùng khóa, ví dụ `CRM bán hàng`, `n8n gửi Zalo`. Tên chỉ để bạn nhận ra khóa trong danh sách.
3. Chọn **vai trò** (xem bảng dưới). Để nguyên `operator` nếu không chắc.
4. Bấm **Tạo**. Khóa hiện ngay bên dưới ô nhập, sau chữ "Key (lưu ngay):".

> Khóa **chỉ hiện đúng một lần**. Sao chép và cất vào nơi an toàn ngay. Rời trang là không xem lại được — danh sách chỉ còn vài ký tự đầu (cột Prefix). Lỡ mất thì thu hồi khóa cũ và tạo khóa mới.

### Chọn vai trò nào

| Vai trò | Tên trên Dashboard | Làm được gì | Khi nào chọn |
|---|---|---|---|
| `operator` | Vận hành | Chat với agent, gửi tin Zalo, dùng Inbox, xem và xuất Contacts | Hầu hết trường hợp tích hợp — **nên dùng** |
| `viewer` | Chỉ xem | Chỉ đọc dữ liệu, không gửi được tin | Phần mềm chỉ cần lấy báo cáo, thống kê |
| `ws_admin` | Quản trị | Mọi thứ, kể cả tạo/xóa kênh, người dùng, khóa API khác | Chỉ khi phần mềm cần tự cấu hình PenAI |

Nguyên tắc: chọn vai trò thấp nhất đủ dùng, và mỗi phần mềm một khóa riêng — khi cần cắt quyền một nơi thì thu hồi đúng khóa đó, các nơi khác không bị ảnh hưởng.

## 2. Kết nối

Bạn cần hai thông tin:

| Thông tin | Giá trị |
|---|---|
| Địa chỉ gốc (base URL) | Địa chỉ bản PenAI của bạn, ví dụ `https://penai.congty.vn` — trong tài liệu ghi là `https://TEN-MIEN-PENAI` |
| Khóa API | Chuỗi `psk_…` vừa tạo |

Mọi lệnh gọi gửi khóa trong header (phần đầu của yêu cầu HTTP) tên `Authorization`:

```
Authorization: Bearer psk_xxxxxxxxxxxxxxxx
```

Với công cụ không cần viết mã (n8n, Make, Postman…): chọn kiểu xác thực **Bearer Token** (hoặc Header Auth) rồi dán khóa vào.

## 3. Kiểm tra kết nối

Làm lần lượt hai bước — bước nào lỗi thì biết ngay hỏng ở đâu.

### Bước 1: máy chủ có chạy không

Lệnh này không cần khóa:

```bash
curl https://TEN-MIEN-PENAI/healthz
```

Kết quả đúng:

```json
{ "ok": true, "version": "1.7.2" }
```

Không ra kết quả này thì sai địa chỉ, hoặc máy chủ PenAI đang không chạy — chưa liên quan đến khóa.

### Bước 2: khóa có dùng được không

```bash
curl https://TEN-MIEN-PENAI/v1/agents \
  -H "Authorization: Bearer psk_xxx"
```

Trên Windows PowerShell:

```powershell
Invoke-RestMethod https://TEN-MIEN-PENAI/v1/agents -Headers @{ Authorization = "Bearer psk_xxx" }
```

Kết quả đúng là danh sách agent của workspace:

```json
{ "agents": [ { "id": "…", "name": "Trợ lý CSKH" } ] }
```

Nhận được danh sách (kể cả danh sách rỗng `{ "agents": [] }`) là **kết nối đã thông**.

### Đọc kết quả khi lỗi

| Kết quả | Nguyên nhân | Cách sửa |
|---|---|---|
| HTTP `401` — `{ "error": "Thiếu Authorization Bearer" }` | Lệnh gọi không có header `Authorization`, hoặc thiếu chữ `Bearer ` phía trước khóa | Thêm đúng header như mục 2 |
| HTTP `401` — `{ "error": "API key không hợp lệ" }` | Khóa sai, chép thiếu ký tự, dính khoảng trắng / xuống dòng, hoặc khóa đã bị thu hồi | Chép lại khóa; nếu mất thì tạo khóa mới |
| HTTP `403` — `{ "error": "Cần quyền … trở lên" }` | Khóa đúng nhưng vai trò không đủ cho lệnh đó | Tạo khóa vai trò cao hơn |
| Không kết nối được, hết thời gian chờ | Sai tên miền, thiếu `https://`, hoặc mạng của bạn chặn | Thử lại Bước 1 từ một máy khác |
| Trả về trang HTML thay vì JSON | Gọi nhầm đường dẫn (ví dụ thiếu `/v1/`) | Kiểm tra lại đường dẫn |

## 4. Thu hồi khóa

Vào **🔑 Khóa API (tích hợp)** → dòng của khóa → **Thu hồi**. Khóa mất hiệu lực ngay; phần mềm đang dùng khóa đó sẽ nhận lỗi `401`.

Nên thu hồi khi: nghi khóa bị lộ, nhân sự giữ khóa nghỉ việc, hoặc ngừng dùng phần mềm đã gắn khóa.

## Giữ khóa an toàn

- Chỉ đặt khóa ở **phía máy chủ** hoặc trong kho bí mật của công cụ (n8n Credentials, biến môi trường…). Không đưa vào mã chạy trên trình duyệt, ứng dụng di động hay file công khai.
- Không gửi khóa qua chat nhóm, email, ảnh chụp màn hình. Không đưa khóa lên GitHub.
- Dán tài liệu này cho AI để nhờ viết mã thì được — nhưng **đừng dán khóa thật**, hãy để `psk_xxx` rồi tự thay sau.

## Bước tiếp theo

- [API gửi tin nhắn Zalo cá nhân](https://help.penai.vn/zalo-api/) — gửi tin theo số điện thoại hoặc UID, kèm ảnh.