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

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

Đăng nhập Dashboard, ở menu bên trái (nhóm Cấu hình) chọn 🔑 Khóa API (tích hợp).
Ô 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.
Chọn vai trò (xem bảng dưới). Để nguyên operator nếu không chắc.
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:

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

Kết quả đúng:

{ "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

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

Trên Windows 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:

{ "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 — gửi tin theo số điện thoại hoặc UID, kèm ảnh.