# API 認證 (/getting-started/authentication)





API 認證 [#api-認證]

Recur API 使用 API Key 進行認證。本文件說明不同類型的 API Key 及其使用方式。

API Key 類型 [#api-key-類型]

Recur 提供兩種類型的 API Key：

| 類型                  | 前綴       | 用途   | 權限   |
| ------------------- | -------- | ---- | ---- |
| **Secret Key**      | `sk_xxx` | 後端使用 | 完整權限 |
| **Publishable Key** | `pk_xxx` | 前端使用 | 限制權限 |

Secret Key [#secret-key]

Secret Key 擁有完整的 API 權限，包括：

* 建立和管理 Checkout Sessions
* 讀取訂單和訂閱資料
* 設定 metadata
* 取消訂閱

<Callout type="error">
  **安全警告**：Secret Key 必須保密，只能在後端伺服器使用。切勿：

  * 在前端代碼中使用
  * 提交到版本控制系統
  * 在公開場合分享
</Callout>

Publishable Key [#publishable-key]

Publishable Key 用於前端整合，權限受限：

* 載入結帳表單
* 取得商品/方案資訊
* 初始化 SDK

<Callout type="info">
  Publishable Key 可以安全地在前端代碼中使用，但仍建議限制使用網域。
</Callout>

環境 [#環境]

Recur 提供兩個環境：

| 環境             | Key 前綴                  | 用途   | 金流   |
| -------------- | ----------------------- | ---- | ---- |
| **Sandbox**    | `sk_test_` / `pk_test_` | 測試環境 | 模擬付款 |
| **Production** | `sk_live_` / `pk_live_` | 正式環境 | 真實付款 |

Sandbox 環境 [#sandbox-環境]

使用 Sandbox 環境進行開發和測試：

* 使用測試 API Key（`sk_test_xxx`）
* 使用 PAYUNi 測試卡號
* 不會產生真實交易

**測試卡號**：

| 卡號                    | 說明                                |
| --------------------- | --------------------------------- |
| `4147-6310-0000-0001` | VISA 測試卡（正常授權成功）                  |
| `3560-5110-0000-0001` | JCB 測試卡（正常授權成功）                   |
| `4147-6310-0000-0002` | VISA 測試卡（模擬 3D 驗證 ECI 值不符，主動取消授權） |
| `3560-5110-0000-0002` | JCB 測試卡（模擬 3D 驗證 ECI 值不符，主動取消授權）  |

* **有效期**：任意未過期日期
* **CVV（背面末三碼）**：任意 3 位數

Production 環境 [#production-環境]

上線前，請確保：

1. 將所有 API Key 替換為正式環境的 Key
2. 完成 [升級正式環境](/help/account/production-upgrade) 流程
3. 設定正確的 Webhook URL

認證方式 [#認證方式]

Authorization Header（推薦） [#authorization-header推薦]

```bash
curl https://api.recur.tw/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_xxx"
```

專用 Header [#專用-header]

```bash
# Secret Key
curl https://api.recur.tw/v1/checkout/sessions \
  -H "X-Recur-Secret-Key: sk_test_xxx"

# Publishable Key
curl https://api.recur.tw/v1/products \
  -H "X-Recur-Publishable-Key: pk_test_xxx"
```

在程式碼中使用 [#在程式碼中使用]

Node.js / TypeScript [#nodejs--typescript]

```typescript
// 使用環境變數儲存 API Key
const RECUR_SECRET_KEY = process.env.RECUR_SECRET_KEY;

const response = await fetch('https://api.recur.tw/v1/checkout/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${RECUR_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    productId: 'prod_xxx',
    mode: 'SUBSCRIPTION',
    successUrl: 'https://example.com/success',
    cancelUrl: 'https://example.com/cancel',
  }),
});
```

前端 SDK [#前端-sdk]

```typescript
import { RecurProvider } from 'recur-tw';

function App() {
  return (
    <RecurProvider publishableKey="pk_test_xxx">
      {/* 您的應用程式 */}
    </RecurProvider>
  );
}
```

取得 API Key [#取得-api-key]

1. 登入 [Recur 後台](https://app.recur.tw)
2. 前往 **設定 → 開發者 → API 金鑰**
3. 點擊「顯示」查看完整 Key
4. 使用「重新產生」來輪換 Key

安全最佳實踐 [#安全最佳實踐]

1. **使用環境變數** - 不要硬編碼 API Key
2. **最小權限原則** - 前端只用 Publishable Key
3. **定期輪換** - 定期重新產生 API Key
4. **監控使用量** - 在後台查看 API 呼叫記錄
5. **限制網域** - 設定允許使用 Publishable Key 的網域

```bash
# .env.local
RECUR_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_RECUR_PUBLISHABLE_KEY=pk_test_xxx
```

錯誤處理 [#錯誤處理]

認證相關的常見錯誤：

| HTTP 狀態 | 錯誤代碼           | 說明               |
| ------- | -------------- | ---------------- |
| 401     | `unauthorized` | API Key 無效或缺失    |
| 403     | `forbidden`    | API Key 無權限執行此操作 |

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided"
  }
}
```

下一步 [#下一步]

* [5 分鐘快速開始](/getting-started/quick-start) - 實作第一個結帳流程
* [API Reference](/api) - 完整 API 文件