> ## 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 平台 API 憑證

> Platform 整合指南 - Ace Data Cloud

為一個 Application 建立業務 API 憑證。建立回應可能包含可直接呼叫 `https://api.acedata.cloud/**` 的 Token，或 Proxy 類型憑證的使用者名稱/密碼；必須按秘密處理。

## 準備工作

1. 建立 [Account Token](https://platform.acedata.cloud/documents/platform-token)。
2. 從[Application 清單](https://platform.acedata.cloud/documents/platform-application-list)取得本人擁有的 `application_id`。

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export APPLICATION_ID='你的 Application ID'
```

## 介面概覽

| 項目 | 內容 |
| - | - |
| 方法 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/credentials/` |
| 驗證 | Account Token，OAuth token 需 `credentials:write` |
| Body | JSON |

## 請求主體

| 欄位 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `application_id` | UUID | 是 | 目標 Application |
| `name` | string | 否 | 憑證顯示名稱 |
| `limited_amount` | number / null | 否 | 單一憑證用量上限；`null` 表示不設獨立上限 |
| `expired_at` | datetime / null | 否 | ISO 8601 到期時間 |
| `allowed_api_ids` | UUID\[] / null | 否 | 僅允許呼叫這些 API；空陣列會正規化為不限制 |
| `host` | string | 否 | 憑證 host 資訊 |
| `for_user_id` | string | 否 | Application 所有者為其他使用者簽發授權憑證時使用 |
| `tags` / `metadata` | array / object | 否 | 自訂擴充資料 |

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{\"application_id\":\"${APPLICATION_ID}\",\"name\":\"production\",\"limited_amount\":50}"
```

## 回應說明

成功回傳 `201` 和 Credential 物件：

* API/Agent 類型服務通常回傳 `type=Token` 和 `token`；
* Proxy 類型服務通常回傳 `type=Identity` 和 `username` / `password`，且一個 Proxy Application 只允許一枚憑證；
* `id`、`user_id`、`creator_id`、`used_amount` 和時間欄位由伺服器端產生。

目前清單和詳細資料介面也會回傳憑證明文，但用戶端不應依賴這個歷史行為。建立後立即儲存，避免把回應寫入日誌；未來介面可能改為脫敏回傳。

## 錯誤處理

* `400`：欄位格式錯誤、未知 `allowed_api_ids`、Proxy Application 已有憑證或其他建立限制。
* `401`：Account Token 無效。
* `403/404`：無權存取目標 Application，或 Application/授權使用者不存在。

## 下一步

* [取得 API 憑證清單](https://platform.acedata.cloud/documents/platform-credential-list)
* [輪換 API 憑證](https://platform.acedata.cloud/documents/platform-credential-rotate)
* [刪除 API 憑證](https://platform.acedata.cloud/documents/platform-credential-delete)
* [查看呼叫紀錄](https://platform.acedata.cloud/documents/platform-usage-list)


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