> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理 AceDataCloud 平台帳戶權杖（Account Token）

> Platform 整合指南 - Ace Data Cloud

**帳戶權杖（Account Token，舊稱 Platform Token）** 是開發者透過程式設計方式管理 AceDataCloud 平台資源（服務申請、API 憑證、訂單、呼叫記錄、餘額、檔案等）的「帳號級金鑰」。它的作用類似前端登入後的使用者 Token，預設沒有過期時間；一般使用者只能管理自己的權杖，超級管理員可依權限管理其他帳戶權杖。

帳戶權杖以所屬帳號的目前權限存取平台介面：基礎權限、直接授予的權限及所屬使用者群組權限合併生效；加入群組或移出群組後，下次請求即依新權限判斷。存取具體申請、訂單等資源仍需透過歸屬驗證。帳戶權杖預設不過期，請只在可信任環境使用並妥善保管。

> ℹ️ 本介面屬於 **AceDataCloud 平台管理 API**，統一前綴 `https://platform.acedata.cloud/api/v1/`。完整介面索引見[取得 AceDataCloud 平台文件列表](https://platform.acedata.cloud/documents/platform-document-list)。

## 帳戶權杖 vs API 憑證

新手最容易混淆的兩類金鑰，請先看清楚：

| 維度 | **帳戶權杖**（本文檔） | **API 憑證（Credential）** |
| - | - | - |
| 用途 | 呼叫 `https://platform.acedata.cloud/**` 管理類介面 | 呼叫 `https://api.acedata.cloud/**` 業務介面（OpenAI、Midjourney、Suno、Veo 等） |
| 格式 | `platform-v1-` + 64 位十六進位（共 76 字元） | 32 位十六進位 |
| 一個帳號 | 通常 1–2 枚 | 每個服務申請 1–N 枚 |
| 建立入口 | [Account Token 控制台](https://platform.acedata.cloud/console/platform-tokens) | [建立 AceDataCloud 平台 API 憑證](https://platform.acedata.cloud/documents/platform-credential-create) |
| 失效條件 | 刪除後立即失效；`expiration` 非空時到期失效 | 可以設定額度上限、過期時間、綁定來源 IP |

如果你只是想調一下 GPT-4.1，要的是 **API 憑證**，不是帳戶權杖。
如果你要寫自動化指令碼管理儲值、看每月帳單、批量發憑證給團隊成員，那才用帳戶權杖。

***

## 在控制台一鍵建立（推薦）

1. 登入 [https://platform.acedata.cloud](https://platform.acedata.cloud)。
2. 進入側邊欄 →「開發者」→「[Account Token](https://platform.acedata.cloud/console/platform-tokens)」。
3. 點擊右上角「建立」按鈕，立刻得到一枚 `platform-v1-...` 權杖，**點複製按鈕儲存到密碼管理器**。

![Account Token 控制台](https://cdn.acedata.cloud/6g86oz.png)

> ⚠️ 目前建立、列表和詳情回應都會傳回權杖明文。請把整個回應按秘密處理，不要寫入日誌、分析平台或前端持久化；用戶端也不應依賴列表長期保持明文傳回。

***

## 用 API 建立帳戶權杖

### 介面概覽

| 項 | 內容 |
| - | - |
| 方法 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| 驗證 | ✅ 任意已有的帳戶權杖 或 瀏覽器登入狀態 JWT |
| Body | `application/json`（可傳空物件 `{}`） |

### 驗證說明（雞生蛋問題）

> 第一枚權杖怎麼來？答案是**走控制台**——瀏覽器登入後，控制台用 JWT 驗證呼叫 `POST /platform-tokens/`，把第一枚權杖發給你。
> 之後你可以用任何一枚已有的 `platform-v1-...` 權杖再建立更多。

請求標頭格式：

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
Content-Type: application/json
```

### 請求範例

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/platform-tokens/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'
```

### 回應（HTTP 201）

```json theme={null}
{
  "id": "3264f1aa-cbe1-4e2c-a434-95adba4f8304",
  "token": "platform-v1-<REDACTED>",
  "expiration": null,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "created_at": "2026-04-26T15:50:11.123456Z",
  "updated_at": "2026-04-26T15:50:11.123456Z",
  "used_at": null
}
```

### 欄位說明

| 欄位 | 類型 | 說明 |
| - | - | - |
| `id` | UUID | 權杖主鍵，刪除 / 查詢詳情時使用 |
| `token` | string | 帳戶權杖明文。格式 `platform-v1-` + 64 位十六進位（共 76 字元），必須按秘密處理 |
| `expiration` | int \| null | 過期時間（秒級時間戳）。`null` 表示未設定到期時間 |
| `user_id` | UUID | 所屬使用者 ID。也是後續所有列表介面必須傳的 `?user_id=` 參數值 |
| `created_at` | datetime (ISO8601) | 建立時間 |
| `updated_at` | datetime (ISO8601) | 更新時間 |
| `used_at` | datetime \| null | 上次被用於驗證的時間。從未使用過則為 `null`，可用來發現「殭屍權杖」 |

***

## 取得帳戶權杖列表

### 介面概覽

| 項 | 內容 |
| - | - |
| 方法 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/` |
| 驗證 | ✅ 需要帳戶權杖 |

### 必傳查詢參數

> ⚠️ **必須帶 `?user_id=<your_user_id>`**。原因：列表介面對分頁結果**逐物件**做權限驗證，沒帶 `user_id` 時第一個不屬於你的物件就會被拒絕，傳回 `403 permission_denied`。

如何取得 `user_id`：

1. 瀏覽器開啟 [https://auth.acedata.cloud/user/profile](https://auth.acedata.cloud/user/profile)，頁面頂部顯示完整 UUID。
2. 或者用 `POST /platform-tokens/` 的回傳值裡的 `user_id` 欄位直接回填。

### 查詢參數

| 參數 | 必填 | 類型 | 說明 |
| - | - | - | - |
| `user_id` | ✅ | UUID | 目前帳戶的使用者 ID |
| `limit` | ❌ | int | 單頁筆數，預設 10，最大 100 |
| `offset` | ❌ | int | 偏移 |
| `ordering` | ❌ | string | 排序欄位，預設 `-created_at` |

### 請求範例

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b&limit=5' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

### 回應（HTTP 200）

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "51c575a2-801c-4211-bc47-711452a8c8c9",
      "token": "platform-v1-<REDACTED>",
      "expiration": null,
      "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
      "created_at": "2026-04-26T15:41:32.761705Z",
      "updated_at": "2026-04-26T15:41:32.761726Z",
      "used_at": null
    }
  ]
}
```

> 本介面的分頁回應使用 `count` + `items`。其他平台介面可能使用不同結構，請以對應文件和實際回應為準。

***

## 取得帳戶權杖詳情

| 項 | 內容 |
| - | - |
| 方法 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**結尾無斜線**） |
| 驗證 | ✅ 僅權杖建立者或超級管理員可存取 |

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/platform-tokens/51c575a2-801c-4211-bc47-711452a8c8c9' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

回傳結構與列表元素一致，`HTTP 200`。

***

## 刪除帳戶權杖

| 項 | 內容 |
| - | - |
| 方法 | `DELETE` |
| URL | `https://platform.acedata.cloud/api/v1/platform-tokens/<id>`（**結尾無斜線**） |
| 驗證 | ✅ 僅權杖建立者或超級管理員可刪除 |

```shell theme={null}
curl -X DELETE 'https://platform.acedata.cloud/api/v1/platform-tokens/3264f1aa-cbe1-4e2c-a434-95adba4f8304' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

* 成功回傳 `HTTP 204 No Content`，無回應主體。
* 刪除後該權杖**立即失效**，所有正在使用它的服務會馬上收到 `401`。
* 再次查詢該 `id` 會回傳 `404`。

> ⚠️ 刪除不可逆。如果你懷疑權杖洩漏，可以**先建立一枚新的，切換業務端，再刪除舊的**。

***

## 不支援的操作

| 操作 | HTTP | 說明 |
| - | - | - |
| `PATCH` 修改 | 405 | 帳戶權杖建立後**不支援任何欄位修改**。需要重新命名等用途請刪除後重建 |
| `PUT` 替換 | 405 | 同上 |

***

## 錯誤碼速查

| HTTP | `code` | 常見原因 |
| - | - | - |
| 401 | `not_authenticated` | 未帶 `Authorization` 標頭，或權杖已被刪除 |
| 403 | `permission_denied` | 列表介面未帶 `?user_id=`，或存取別人的權杖詳情 |
| 404 | `not_found` | `id` 不存在或已被刪除 |
| 405 | `method_not_allowed` | 對詳情介面發送了 `PATCH`/`PUT` |

錯誤回應統一格式：

```json theme={null}
{
  "detail": "You do not have permission to perform this action.",
  "code": "permission_denied",
  "trace_id": "0a88956213edf6e62b71695ee2df0eff"
}
```

排查時將 `trace_id` 提供給客服或貼在工單裡，可快速定位日誌。

***

## 完整程式碼範例

### Python

```python theme={null}
import os
import requests

BASE = "https://platform.acedata.cloud/api/v1"
PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {PLATFORM_TOKEN}",
    "content-type": "application/json",
}

# 1. 创建新令牌
created = requests.post(f"{BASE}/platform-tokens/", headers=headers, json={}).json()
print("新令牌：", created["token"])
print("UserID：", created["user_id"])

# 2. 列表
listing = requests.get(
    f"{BASE}/platform-tokens/",
    headers=headers,
    params={"user_id": USER_ID, "limit": 50},
).json()
print(f"共 {listing['count']} 枚令牌")

# 3. 删除（注意末尾无斜杠）
resp = requests.delete(f"{BASE}/platform-tokens/{created['id']}", headers=headers)
assert resp.status_code == 204, resp.text
```

### Node.js

```javascript theme={null}
const BASE = 'https://platform.acedata.cloud/api/v1'
const PLATFORM_TOKEN = process.env.PLATFORM_TOKEN
const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'

const headers = {
  accept: 'application/json',
  authorization: `Bearer ${PLATFORM_TOKEN}`,
  'content-type': 'application/json',
}

// 创建
const created = await fetch(`${BASE}/platform-tokens/`, {
  method: 'POST',
  headers,
  body: '{}',
}).then((r) => r.json())

// 列表
const url = new URL(`${BASE}/platform-tokens/`)
url.searchParams.set('user_id', USER_ID)
const listing = await fetch(url, { headers }).then((r) => r.json())
console.log(`共 ${listing.count} 枚令牌`)

// 删除（末尾无斜杠）
await fetch(`${BASE}/platform-tokens/${created.id}`, { method: 'DELETE', headers })
```

***

## 在其他平台 API 中使用

將 `platform-v1-...` 直接放到 `Authorization: Bearer ...` 標頭即可呼叫任何需要驗證的平台介面：

```shell theme={null}
curl 'https://platform.acedata.cloud/api/v1/applications/?user_id=89518d07-5560-4b05-92c1-667f3ddf6a4b' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}"
```

> 與 `https://api.acedata.cloud/**` 業務介面（OpenAI、Midjourney、Suno、Veo 等）所用的 32 位元十六進位 API 憑證**完全不同**。請勿混用——將帳戶權杖寫到業務介面會得到 `401`，反之亦然。

***

## 相關介面

* [取得 AceDataCloud 平台服務申請列表](https://platform.acedata.cloud/documents/platform-application-list) — 使用帳戶權杖查看自己申請了哪些服務
* [建立 AceDataCloud 平台 API 憑證](https://platform.acedata.cloud/documents/platform-credential-create) — 使用帳戶權杖簽發業務 API 使用的 32 位元憑證
* [取得 AceDataCloud 平台 API 呼叫紀錄](https://platform.acedata.cloud/documents/platform-usage-list) — 查帳與除錯
* [取得 AceDataCloud 平台訂單列表](https://platform.acedata.cloud/documents/platform-order-list) — 查詢儲值歷史


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.