API Keys API

Các endpoint này cho phép bạn quản lý các khóa API của tài khoản từ mã nguồn. Tất cả chúng chỉ hoạt động trên các khóa của chính tài khoản đang thực hiện lệnh gọi.

Có hai loại khóa và chúng nằm trên các đường dẫn riêng biệt:

Khóa chính của bạn — khóa có toàn quyền duy nhất nằm trong Cài đặt → Tích hợp → Khóa API. Tra cứu bản xem trước bị ẩn của nó, kiểm tra mức sử dụng giới hạn tốc độ, xoay vòng hoặc thu hồi khóa. Đây là các endpoint /api-keys/current, /api-keys/rotate và /api-keys/usage bên dưới.
Khóa phạm vi (Scoped keys) — các khóa bổ sung, có tên mà bạn tạo cho một công việc cụ thể, mỗi khóa chỉ giới hạn ở các phần của API mà bạn chọn. Đây là các endpoint /api-keys và /api-keys/{id} trong phần Khóa phạm vi. Không có gì về khóa chính của bạn thay đổi khi bạn tạo một khóa mới; các tích hợp hiện có vẫn tiếp tục hoạt động bình thường.

Tất cả các đường dẫn bên dưới đều tương đối so với URL cơ sở của API:

https://api.youraiconnector.com/v1

Mọi yêu cầu đều phải được xác thực. Xem Xác thực để biết bốn phương thức được chấp nhận. Các ví dụ ở đây sử dụng tiêu đề X-API-Key (và một dạng tham số truy vấn cho cURL).

Đọc phần này trước. Việc xoay vòng hoặc thu hồi khóa của bạn sẽ có hiệu lực ngay lập tức. Ngay khi một trong hai lệnh gọi thành công, khóa cũ sẽ ngừng hoạt động — mọi tích hợp vẫn đang sử dụng khóa đó sẽ bắt đầu nhận lỗi 401. Hãy lên kế hoạch: thực hiện xoay vòng trong thời gian bảo trì và cập nhật tất cả các tích hợp của bạn ngay lập tức.

Lấy siêu dữ liệu khóa hiện tại

Trả về khóa đang hoạt động của bạn: khóa đầy đủ trong api_key khi có bản sao có thể truy xuất, bản xem trước bị ẩn (4 ký tự đầu và 4 ký tự cuối), và ngày tạo khóa nếu có. api_key là null đối với các khóa được tạo trước khi các bản sao có thể truy xuất được lưu giữ — hãy xoay vòng một lần và khóa mới có thể được hiển thị lại sau này.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Nếu tài khoản không có khóa API, phản hồi sẽ là 404 với { "success": false, "error": "No API key found for this account" }.

Lấy mức sử dụng giới hạn tốc độ

Trả về mức sử dụng giới hạn tốc độ của bạn trong cửa sổ hiện tại: giới hạn yêu cầu mỗi cửa sổ, số lượng yêu cầu đã được tính cho đến nay, số lượng còn lại và thời điểm cửa sổ đặt lại. Hãy sử dụng thông tin này để xây dựng cơ chế điều tiết phía máy khách (client-side throttling) để tích hợp của bạn tự giảm tải trước khi gặp phải các phản hồi 429.

GET /api-keys/usage

cURL

curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Nếu chưa có yêu cầu nào được ghi lại trong cửa sổ hiện tại, mức sử dụng sẽ được báo cáo là bằng không và phản hồi bao gồm trường note giải thích lý do.

Xoay vòng khóa

Tạo một khóa API mới và vô hiệu hóa khóa trước đó trong cùng một bước. Hãy sử dụng tính năng này nếu bạn nghi ngờ khóa của mình đã bị lộ, hoặc như một phần của chính sách xoay vòng thông tin xác thực định kỳ.

POST /api-keys/rotate

Khóa mới chỉ được hiển thị một lần duy nhất. Nó được trả về trong phản hồi này và sau đó không thể truy xuất đầy đủ — hãy lưu trữ nó an toàn ngay khi bạn nhận được. Khóa cũ sẽ ngừng hoạt động ngay khi lệnh gọi này thành công, vì vậy hãy cập nhật mọi tích hợp đã sử dụng khóa đó.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Phản hồi

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Thu hồi khóa

Xóa vĩnh viễn khóa API của tài khoản bạn. Việc thu hồi có hiệu lực ngay lập tức: mọi yêu cầu tiếp theo sử dụng khóa đã bị thu hồi — bao gồm các tích hợp như Make, Zapier hoặc các tập lệnh tùy chỉnh — đều bị từ chối với mã 401. Để khôi phục quyền truy cập API sau đó, hãy tạo khóa mới từ cài đặt tài khoản khi đã đăng nhập vào ứng dụng.

DELETE /api-keys/current

Không thể hoàn tác. Không giống như việc xoay vòng, thu hồi không cung cấp cho bạn khóa thay thế. Chỉ thu hồi khi bạn có ý định dừng quyền truy cập API (ví dụ: khóa bị rò rỉ mà bạn không thể thay thế ngay lập tức).

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Nếu tài khoản không có khóa để thu hồi, phản hồi sẽ là 404.

Khóa phạm vi

Khóa phạm vi là một khóa API bổ sung mà bạn tạo cho một công việc cụ thể, chỉ mang quyền truy cập mà công việc đó cần. Trường hợp điển hình: bạn muốn trỏ một bảng điều khiển khách hàng, công cụ báo cáo hoặc tập lệnh nội bộ vào tài khoản của mình mà không cần cung cấp khóa có thể gửi tin nhắn, thay đổi tác nhân AI hoặc mua số điện thoại.

Sự hạn chế đi kèm với chính khóa đó, vì vậy bất kỳ ai giữ khóa chỉ có thể thực hiện những gì bạn đã cho phép khi tạo nó.

Những gì bạn có thể hạn chế

Trường	Ý nghĩa
`read_only`	`true` (mặc định) nghĩa là chỉ cho phép các yêu cầu đọc. Mọi hành động tạo, cập nhật hoặc xóa đều bị từ chối.
`tags`	Danh sách các phần API mà khóa có thể sử dụng, được viết bằng cùng tên phần bạn thấy trong tài liệu này và trong API explorer — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, v.v. Danh sách trống nghĩa là tất cả các phần.
`sub_account_ids`	Các tài khoản được quản lý mà khóa có thể tác động. Để trống nghĩa là chỉ tài khoản của riêng bạn; `["*"]` nghĩa là bất kỳ tài khoản nào bạn thực sự quản lý. Quyền sở hữu vẫn được kiểm tra trên mọi yêu cầu.
`rate_limit_per_min`	Số yêu cầu mỗi phút cho khóa này, được tính trong ngân sách riêng của nó để không sử dụng hết hạn mức của các tích hợp khác của bạn. Mặc định là `60` và không thể đặt cao hơn `300`.

Bạn cũng có thể cung cấp cho khóa một ngày expires_at (ISO 8601 và phải là ngày trong tương lai). Sau thời điểm đó, khóa sẽ tự động ngừng hoạt động. Nếu bỏ qua, khóa sẽ không bao giờ hết hạn cho đến khi bạn thu hồi nó.

Các yêu cầu bị từ chối sẽ được chặn lại. Nếu một yêu cầu nằm ngoài phạm vi cho phép của khóa, nó sẽ bị từ chối thay vì được thông qua: một hành động ghi với khóa chỉ đọc sẽ trả về 403 với error_code: "key_read_only", và bất kỳ hành động nào nằm ngoài các phần được phép của khóa sẽ trả về 403 với error_code: "key_scope_denied". Nếu một khóa phạm vi nhận được 403 không mong đợi, endpoint bạn đã gọi đơn giản là không nằm trong phạm vi của nó — hãy mở rộng phạm vi khóa hoặc sử dụng khóa chính của bạn.

Chỉ chủ sở hữu tài khoản mới quản lý được khóa. Bốn endpoint này yêu cầu khóa chính của bạn hoặc phiên làm việc của chủ sở hữu trong ứng dụng. Khóa phạm vi không bao giờ có thể liệt kê, tạo, chỉnh sửa hoặc thu hồi khóa — bao gồm cả chính nó — vì vậy một khóa bị hạn chế không bao giờ có thể được sử dụng để tạo ra một khóa có quyền rộng hơn. Cố gắng thực hiện sẽ trả về 403 với error_code: "key_scope_denied". Vì lý do tương tự, API Keys không phải là một phần bạn có thể cấp quyền: yêu cầu thực hiện điều này sẽ trả về 400 với error_code: "invalid_scopes".

Liệt kê các khóa phạm vi

Trả về các khóa phạm vi của tài khoản, khóa mới nhất hiển thị trước (tối đa 200), bao gồm cả các khóa đã bị thu hồi để bạn có thể thấy những gì đã bị hủy bỏ và khi nào. Chỉ các bản xem trước bị ẩn mới được trả về — giá trị của khóa phạm vi chỉ được hiển thị một lần, tại thời điểm tạo và không bao giờ có thể truy xuất sau đó.

GET /api-keys

cURL

curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Tạo một khóa phạm vi

Tạo một khóa phạm vi mới và trả về giá trị của nó một lần duy nhất.

POST /api-keys

Khóa chỉ được hiển thị một lần. Nó chỉ xuất hiện trong phản hồi này và không bao giờ xuất hiện ở bất kỳ nơi nào khác — không có cách nào để tra cứu lại sau đó. Hãy lưu trữ nó ngay khi bạn nhận được. Nếu bạn làm mất, hãy thu hồi nó và tạo một khóa khác.

Các trường trong phần thân (Body) — tất cả đều là tùy chọn:

Trường	Loại	Ghi chú
`label`	string	Tên riêng của bạn cho khóa, được hiển thị trong danh sách và trong Cài đặt.
`scopes`	object	Bốn trường trong bảng trên. Nếu bỏ qua toàn bộ đối tượng này, bạn sẽ nhận được mặc định an toàn: chỉ đọc, giới hạn ở `Analytics`, chỉ tài khoản của bạn, 60 yêu cầu mỗi phút.
`expires_at`	Ngày ISO 8601	Ngày hết hạn tùy chọn, phải là thời điểm trong tương lai.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Phản hồi — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Một vài chi tiết cần lưu ý khi bạn xây dựng dựa trên phần này:

Việc bỏ qua scopes không giống như việc gửi một danh sách tags trống. Hãy bỏ qua scopes hoàn toàn để nhận mặc định an toàn (chỉ đọc, chỉ Analytics). Nếu bạn cố tình gửi "tags": [], khóa có thể sử dụng mọi phần — điều đó được hiểu là một yêu cầu có chủ đích cho một khóa không bị hạn chế.
read_only vẫn là true trừ khi bạn gửi rõ ràng false. Một lỗi đánh máy hoặc một cờ bị thiếu sẽ không bao giờ vô tình tạo ra một khóa có quyền ghi.

Cập nhật khóa phạm vi

Thay đổi nhãn, phạm vi và/hoặc ngày hết hạn của khóa. Gửi bất kỳ kết hợp nào trong ba yếu tố này; nếu không gửi gì cả sẽ trả về 400.

PATCH /api-keys/{id}

{id} là id của khóa từ danh sách (giá trị key_...), không bao giờ là chính khóa đó.

Các phạm vi được thay thế, không phải hợp nhất. Bất cứ thứ gì bạn gửi sẽ trở thành tập hợp quyền hoàn chỉnh của khóa. Điều này là có chủ đích: việc thu hẹp phạm vi của khóa sẽ không bao giờ vô tình để lại quyền truy cập rộng hơn trước đó. Luôn gửi toàn bộ đối tượng scopes mà bạn muốn, không chỉ trường bạn đang thay đổi.

Giá trị của khóa không bao giờ thay đổi. Không có tính năng xoay vòng tại chỗ (rotate-in-place) cho khóa phạm vi — để thay đổi, hãy tạo một khóa mới và thu hồi khóa cũ, để quyền truy cập của thông tin xác thực không bao giờ thay đổi đối với một tích hợp vẫn đang giữ nó.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Phản hồi

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Nếu không có khóa nào với id đó trong tài khoản của bạn, phản hồi sẽ là 404.

Thu hồi một khóa có phạm vi (scoped key)

Việc thu hồi có hiệu lực ngay lập tức: yêu cầu tiếp theo sử dụng khóa đó sẽ bị từ chối với mã 401. Khóa chính và mọi khóa có phạm vi khác của bạn đều không bị ảnh hưởng.

DELETE /api-keys/{id}

Khóa vẫn nằm trong danh sách của bạn với trạng thái "revoked": true, vì vậy bạn vẫn lưu giữ được hồ sơ về những gì đã tồn tại và những gì nó có thể truy cập. Việc thu hồi một khóa đã bị thu hồi sẽ thành công và không làm thay đổi bất cứ điều gì.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Các lỗi API của API Keys

Các endpoint của API-key trả về phong bì lỗi tiêu chuẩn:

{
  "success": false,
  "error": "No API key found for this account"
}

Trên một endpoint API-key, khóa bị thiếu hoặc không hợp lệ sẽ trả về 401 và tài khoản không có khóa trong hồ sơ sẽ trả về 404. Các mã chia sẻ mà mọi endpoint có thể trả về — 400, 403 (gói của bạn không bao gồm quyền truy cập API), 429 (giới hạn tốc độ) và 500 — được liệt kê cùng với hướng dẫn thử lại trong Lỗi & Phân trang.

Các điểm cuối (endpoints) của khóa có phạm vi bổ sung một vài mã được đặt tên trong trường error_code để bạn có thể phân biệt các trường hợp:

`error_code`	Trạng thái	Điều gì đã xảy ra
`key_read_only`	`403`	Một khóa chỉ đọc đã cố gắng thực hiện thao tác ghi.
`key_scope_denied`	`403`	Khóa không được phép sử dụng trên điểm cuối đó hoặc tài khoản được quản lý đó — hoặc một khóa có phạm vi đã cố gắng quản lý các khóa API, điều này không bao giờ được cho phép.
`invalid_scopes`	`400`	Các phạm vi được yêu cầu bao gồm phần `API Keys`. Các khóa không thể quản lý các khóa khác.
`404`	`404`	Không có khóa nào với ID đó trong tài khoản của bạn.

Các bước tiếp theo

Xác thực — bốn cách để xác thực một yêu cầu và cách thực thi các phạm vi khóa.
Lỗi & Giới hạn tốc độ — các mã trạng thái và giới hạn 300 yêu cầu/phút.

API Keys API #

Lấy siêu dữ liệu khóa hiện tại #

Lấy mức sử dụng giới hạn tốc độ #

Xoay vòng khóa #

Thu hồi khóa #

Khóa phạm vi #

Liệt kê các khóa phạm vi #

Tạo một khóa phạm vi #

Cập nhật khóa phạm vi #

Thu hồi một khóa có phạm vi (scoped key) #

Các lỗi API của API Keys #

Các bước tiếp theo #

API Keys API

Lấy siêu dữ liệu khóa hiện tại

Lấy mức sử dụng giới hạn tốc độ

Xoay vòng khóa

Thu hồi khóa

Khóa phạm vi

Liệt kê các khóa phạm vi

Tạo một khóa phạm vi

Cập nhật khóa phạm vi

Thu hồi một khóa có phạm vi (scoped key)

Các lỗi API của API Keys

Các bước tiếp theo