# 建立API Key

此 API 用於建立一把新的客戶 API Key，僅 **Master Key** 可呼叫此 API。

建立成功後，系統只會在這一次回應中回傳 API Key 的明文值（value）。之後無法再透過任何 API 重新取得該明文。

若請求中未提供 expires_at，系統將預設設定為建立時間後 90 天。

```javascript
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/api-keys' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <master-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "customer_name": "ACME Corp",
      "contact": "alice@example.com",
      "purpose": "UAT"
    }
  }'
```

#### Request Headers

| **Key** | **Value** |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | Bearer &lt;master-key> |
| Content-Type | application/json |

#### Request Payload

```javascript
{
"metadata": {
"customer_name": "ACME Corp",
"contact": "[alice@example.com](mailto:alice@example.com)",
"purpose": "UAT"
},
"expires_at": null
}
```

**Field Explanation**

| **Field** | **Type** | **Detail** | **Required** |
| --- | --- | --- | --- |
| metadata | object | API Key 的描述資訊，可用於記錄客戶名稱、聯絡人、用途等 | false |
| expires_at | string | null | API Key 到期時間。可省略、可指定 ISO8601 時間、可設為 null 代表不過期 | false |

**補充說明：**

- expires_at 省略：系統預設為建立日起 90 天

- expires_at = null：不設定到期時間

- expires_at = "2026-03-16T00:00:00Z"：指定到期時間

#### Response Body

```javascript
{
  "id": "3f90f7e3-7ec5-4c68-8bd1-38f54e90d390",
  "object": "api_key",
  "value": "sk-live-example-only-once",
  "redacted_value": "sk-xxxxxx...abcd",
  "metadata": {
    "customer_name": "ACME Corp",
    "contact": "alice@example.com",
    "purpose": "UAT"
  },
  "created_at": "2025-12-16T00:00:00Z",
  "expires_at": "2026-03-16T00:00:00Z"
}
```

**Field Explanation**

| **Field** | **Detail** |
| --- | --- |
| id | API Key 的唯一鍵，uuid |
| object | 物件類型，固定為 api_key |
| value | API Key 明文，只會在建立當下回傳一次 |
| redacted_value | 遮罩後的 API Key |
| metadata | API Key 的描述資訊 |
| created_at | API Key 建立時間 |
| expires_at | API Key 到期時間，null 代表不過期 |
