# 创建API token

> 为你的网站、App和AI助手创建、查看、复制和删除BCL API token，选择权限，并管理已连接的App。
>
> Source: https://docs.bcl.my/zh/api-tokens/

API token让你自己的网站、App或AI助手不用你的密码，就能使用你的BCL账号。你在BCL创建token，并选择每个token可以做什么。只有管理员（Admin）可以创建token。

Endpoint和请求格式，请看[BCL API参考文档](https://bcl.my/docs/api)。要连接AI助手，请看[把Claude或ChatGPT连接到BCL](/zh/connect-ai-agent/)或[Set up other AI apps](/zh/ai-agent-setup/)。

## Token在哪里

API token在**Integrations**页面：

1. 在侧边栏前往**Platform Setup** → **Integrations**。

   *(Screenshot: BCL侧边栏的Platform Setup菜单，已标示Integrations)*

2. 打开**API Token**标签页。

   *(Screenshot: Integrations页面，已标示API Token标签页)*

这个标签页有两个部分：**API Tokens**是你自己的token，**Connected Apps**是你用OAuth登录连接的AI App。

## 创建token

每位管理员最多可以有10个token。创建方法：

1. 在**API Token**标签页，点击**Create New API Token**。

   *(Screenshot: API Tokens部分，已标示Create New API Token按钮)*

2. 在**Token Name**输入token会在哪里使用，例如“Kopi Kampung Website”。BCL会建议一个名称，你可以更改。
3. 在**Permissions**下，只勾选App需要的权限：

   | 权限 | 让token可以 | 用于 |
   |---|---|---|
   | **API Read** | 通过API读取表单、交易、顾客、优惠券和其他资料 | 报告、仪表板、把订单同步到另一个系统 |
   | **API Write** | 通过API创建付款链接和更改资料 | 会创建付款链接或更新表单的网站或App |
   | **MCP Read** | 让AI助手查询你的资料 | Claude Code、Cursor、VS Code和其他AI App |
   | **MCP Write** | 让AI助手创建和更改东西 | 你信任、可以让它做更改的AI App |

   *(Screenshot: Create New API Token面板，有Token Name、已标示的Permissions列表和Expiration)*

4. 在**Expiration**选择token什么时候失效：**Never**、**30 days**、**90 days**、**180 days**或**365 days**。
5. 点击**Create Token**。BCL会显示信息`API token "<name>" has been created.`，并把token加入列表。

API权限和MCP权限是分开的。只有**API Read**和**API Write**的token不能用于AI助手，只有MCP权限的token也不能用于API。**API Write**本身不能读取，所以大多数情况下也要勾选**API Read**。Token的权限之后不能更改：请改为创建一个新token。

## 使用token

Token以`bcl_`开头。你的系统在每个请求的`Authorization` header里发送它：

```text
Authorization: Bearer bcl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
```

API的地址是`https://api.bcl.my/v1`。也请发送你自己的`User-Agent`，例如`MyShop/1.0`：BCL会拒绝来自脚本默认user agent的请求，例如单纯的`curl`或`python-requests`。所有endpoint都在[BCL API参考文档](https://bcl.my/docs/api)里。

Token看到的资料和你一样。Token属于创建它的管理员，其他管理员在自己的列表里看不到。

## 再次查看或复制token

BCL会保存你的token，所以你之后可以再次查看。在**API Tokens**列表里：

- 点击**View token**图标（眼睛），在名称下显示token。再点击一次就会隐藏。
- 点击**Copy token**图标复制token。

*(Screenshot: API Tokens列表，已标示一个token那一行的View token和Copy token图标)*

列表也显示每个token的**Abilities**、什么时候**Expires**，以及**Last Used**的时间。已过期的token会在名称旁显示**Expired**，不能再查看或复制。

## 删除token

删除token会切断所有使用它的App。删除方法：

1. 在该token那一行，点击**Delete token**图标（垃圾桶）。
2. 在**Delete API Token**点击**Delete Token**。

   *(Screenshot: Delete API Token确认框，已标示Delete Token按钮)*

所有使用这个token的App会马上失去访问权限。删除后不能恢复。如果App仍然需要访问，就创建一个新token，并放进App里。

## Connected Apps

**Connected Apps**列出你用BCL账号登录（OAuth）连接的AI App，例如Claude、ChatGPT或Cursor。这些App不使用token。每个App都会显示它的权限、你什么时候授权，以及最后使用的时间。

*(Screenshot: API Token标签页的Connected Apps部分)*

要切断某个App，点击它那一行的**Revoke access**图标，然后点击**Revoke Access**。请看[Disconnect an AI app](/zh/connect-ai-agent/#断开ai-app的连接)。

## 小贴士

Token就是你账号的钥匙。几个好习惯可以保护它们：

- **每个App一个token**。用App的名称来命名；AI工具的话，也写上是哪台电脑。万一有一个外泄，你只需删除那个token，其他的照常运作。
- **员工离职时撤销访问权限**。Token和已连接的App属于创建它们的管理员，其他管理员看不到。请离职的管理员先删除自己的token和App，并更换所有他们持有副本的token。
- **绝对不要把token贴在公开的地方**。别把它放在访客看得到的网站代码、公开的Git仓库、截图和聊天群组里。如果token外泄，马上删除它。
- **设置有效期**。设为**Never**的token会一直有效，直到有人删除它。不时查看**Last Used**，删除没人使用的token。

## 常见问题

### 我要怎样拿到API key来创建自己的整合？

前往Platform Setup → Integrations，打开API Token标签页，然后点击Create New API Token。勾选API Read；如果你的系统要创建付款链接或更改资料，也勾选API Write。

### 我的token不见了。我需要创建一个新的吗？

不需要。在API Token标签页，点击该token那一行的View token或Copy token图标。BCL会保存token，所以你可以再次查看。

### 为什么我收到“Token does not have the 'api:write' ability”？

这个token创建时没有勾选API Write。权限之后不能更改，所以请创建一个勾选API Write的新token，再删除旧的。