---
title: API 認證
description: 了解如何使用 API Key 認證 Recur API
---

# API 認證

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

## API Key 類型

Recur 提供兩種類型的 API Key：

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

### Secret Key

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

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

  **安全警告**：Secret Key 必須保密，只能在後端伺服器使用。切勿：
  - 在前端代碼中使用
  - 提交到版本控制系統
  - 在公開場合分享

### Publishable Key

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

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

  Publishable Key 可以安全地在前端代碼中使用，但仍建議限制使用網域。

## 環境

Recur 提供兩個環境：

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

### 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 環境

上線前，請確保：

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

## 認證方式

### Authorization Header（推薦）

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

### 專用 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

```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

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

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

## 取得 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-reference) - 完整 API 文件