API 驗證

所有 Piora API 請求都需要驗證。Piora 使用 Bearer Token 進行 API 驗證。

取得 API Token

在控制面板中產生

登入 Piora 控制面板
進入「設定」>「API Token」
點選「產生新 Token」
為 Token 命名（例如 ci-cd-pipeline）
選擇 Token 權限範圍
點選「建立」

Token 權限

產生 Token 時，你可以選擇以下權限範圍：

權限	說明
`servers:read`	讀取伺服器資訊
`servers:write`	管理伺服器
`applications:read`	讀取應用資訊
`applications:write`	管理應用
`applications:deploy`	部署應用
`databases:read`	讀取資料庫資訊
`databases:write`	管理資料庫
`backups:read`	讀取備份資訊
`backups:write`	管理備份

使用 Token

Bearer Token 驗證

在每個 API 請求的 Authorization 標頭中加入 Token：

curl -X GET https://app.piora.dev/api/v1/servers \
  -H "Authorization: Bearer piora_token_xxxxxxxxxxxx"

各語言範例

// Node.js (fetch)
const response = await fetch('https://app.piora.dev/api/v1/servers', {
  headers: {
    'Authorization': 'Bearer piora_token_xxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
});
const data = await response.json();

# Python (requests)
import requests

response = requests.get(
    'https://app.piora.dev/api/v1/servers',
    headers={'Authorization': 'Bearer piora_token_xxxxxxxxxxxx'}
)
data = response.json()

// Go
req, _ := http.NewRequest("GET", "https://app.piora.dev/api/v1/servers", nil)
req.Header.Set("Authorization", "Bearer piora_token_xxxxxxxxxxxx")
resp, _ := http.DefaultClient.Do(req)

Token 管理

檢視 Token 列表

在「設定」>「API Token」頁面可以查看所有已建立的 Token：

Token 名稱
權限範圍
建立日期
最後使用時間

撤銷 Token

如果 Token 可能已外洩，請立即撤銷：

進入「設定」>「API Token」
找到目標 Token
點選「撤銷」
確認操作

撤銷後，使用該 Token 的所有請求會立即收到 401 Unauthorized 回應。

安全最佳實踐

不要在程式碼中硬編碼 Token — 使用環境變數
不要在版本控制中提交 Token — 將 Token 加入 .gitignore
定期輪換 Token — 建議每 90 天更換
使用最小權限 — 只授予必要的權限範圍
監控使用情況 — 定期檢查 Token 的使用記錄

# 使用環境變數
export PIORA_API_TOKEN=piora_token_xxxxxxxxxxxx

# 在程式中使用
curl -H "Authorization: Bearer $PIORA_API_TOKEN" \
  https://app.piora.dev/api/v1/servers

錯誤代碼

HTTP 狀態碼	說明
`401`	Token 無效或已過期
`403`	Token 權限不足
`429`	超過速率限制