# 管理後台

管理後台是**控制平面**，供你方管理員管理 API key、credit 餘額與方案。它與資料平面（應用程式呼叫的 API）完全分離：管理員以**帳號密碼登入**取得 session，操作不計費、不限流。

{% hint style="info" %}
一般應用程式的整合**不需要**用到本後台；這裡是給負責發放與管控金鑰的管理員看的。
{% endhint %}

## 登入

後台同時提供網頁介面與 API。網頁介面可建立／撤銷 key、調整 credit、管理方案；以下以 API 說明各項操作。

```bash
curl -c cookies.txt -X POST https://api.atlantis.example/admin/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@your-org.example","password":"YOUR_PASSWORD"}'
```

登入成功會設定一個 httpOnly 的 session cookie（後續請求帶上即可）。相關端點：

| 端點                       | 說明                   |
| ------------------------ | -------------------- |
| `POST /admin/api/login`  | 登入，設定 session cookie |
| `POST /admin/api/logout` | 登出                   |
| `GET /admin/api/me`      | 目前登入的管理員資訊           |

## 管理 API key

{% stepper %}
{% step %}

#### 建立 key

指定名稱、方案與初始 credit。回應含**一次性明碼 key**。

```bash
curl -b cookies.txt -X POST https://api.atlantis.example/admin/api/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"行動 App","plan_id":"<plan-uuid>","initial_credit":10000}'
```

```json
{
  "data": {
    "id": "a1b2c3d4-...",
    "key_prefix": "ak_live_3f9a2c7b",
    "raw_key": "ak_live_3f9a2c7b8e1d4a60..."
  },
  "meta": { "request_id": "..." }
}
```

{% hint style="warning" %}
`raw_key` 只回傳這一次，請當場交付給使用者並妥善保存。系統只保存雜湊值，無法再取回明碼。
{% endhint %}
{% endstep %}

{% step %}

#### 列出 key

```bash
curl -b cookies.txt https://api.atlantis.example/admin/api/api-keys
```

回傳每把 key 的前綴、名稱、狀態、所屬方案、credit 餘額與最後使用時間（不含明碼）。
{% endstep %}

{% step %}

#### 撤銷 key

```bash
curl -b cookies.txt -X POST \
  https://api.atlantis.example/admin/api/api-keys/{id}/revoke
```

撤銷立即生效，之後使用該 key 的請求一律 `401`。
{% endstep %}

{% step %}

#### 調整 credit

`delta` 可正（加值）可負（扣回）。

```bash
curl -b cookies.txt -X POST \
  https://api.atlantis.example/admin/api/api-keys/{id}/credit \
  -H "Content-Type: application/json" \
  -d '{"delta":5000}'
```

{% endstep %}
{% endstepper %}

## 管理方案

方案定義一組共用的限流與 credit 規則，建立 key 時指定。

| 端點                      | 說明   |
| ----------------------- | ---- |
| `GET /admin/api/plans`  | 列出方案 |
| `POST /admin/api/plans` | 建立方案 |

建立方案可設定：

| 欄位                     | 說明                    |
| ---------------------- | --------------------- |
| `name`                 | 方案名稱                  |
| `monthly_credit_quota` | 每月 credit 配額（紀錄／重置基準） |
| `rate_limit_rps`       | 每秒請求數上限（留空則用系統預設）     |
| `rate_limit_burst`     | 突發容量（留空則用系統預設）        |

```bash
curl -b cookies.txt -X POST https://api.atlantis.example/admin/api/plans \
  -H "Content-Type: application/json" \
  -d '{"name":"pro","monthly_credit_quota":1000000,"rate_limit_rps":200,"rate_limit_burst":400}'
```

## 安全建議

* 管理員帳號請使用強密碼，並限制可存取後台的人員。
* 依**最小權限**原則發放 API key：每個整合一把獨立 key，方便個別撤銷與稽核。
* 定期檢視 key 列表，撤銷不再使用的 key。

## 下一步

{% content-ref url="/pages/ENpILCR0cyLHZ3mzFJQ4" %}
[端點總覽](/documentation/api-can-kao/endpoints.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/cao-zuo-zhi-nan/admin-console.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.