跳到主要内容

API 认证

通过正确的认证机制保护你的 Pelago API 集成。

API 密钥​

Pelago 使用双密钥认证系统：

密钥类型用途示例
公钥标识你的账户pk_live_xxxxx
私钥签署请求sk_live_xxxxx

获取密钥​

  1. 登录 Pelago 控制台
  2. 前往 设置 → API 密钥
  3. 点击 生成新密钥对
  4. 安全保存私钥（仅显示一次）

环境密钥​

环境密钥前缀用途
沙盒pk_test_ / sk_test_开发与测试
生产pk_live_ / sk_live_正式交易

认证方式​

请求头认证（推荐）​

curl -X POST https://api.pelago.tech/v1/payments \
  -H "Authorization: Bearer pk_live_xxxxx" \
  -H "X-Api-Secret: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "currency": "USD"}'

SDK 认证​

JavaScript：

import { PelagoClient } from '@pelago/sdk';

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY,      // pk_live_xxxxx
  apiSecret: process.env.PELAGO_API_SECRET, // sk_live_xxxxx
  environment: 'production'
});

Python：

from pelago import PelagoClient
import os

pelago = PelagoClient(
    api_key=os.environ['PELAGO_API_KEY'],
    api_secret=os.environ['PELAGO_API_SECRET'],
    environment='production'
)

Go：

import "github.com/polyflow/pelago-go"

client := pelago.NewClient(pelago.Config{
    APIKey:      os.Getenv("PELAGO_API_KEY"),
    APISecret:   os.Getenv("PELAGO_API_SECRET"),
    Environment: pelago.Production,
})

请求签名​

为增强安全性，可对请求进行签名：

import crypto from 'crypto';

function createSignedRequest(
  method: string,
  path: string,
  body: object,
  apiSecret: string
) {
  const timestamp = Date.now();
  const payload = `${timestamp}.${method}.${path}.${JSON.stringify(body)}`;
  
  const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(payload)
    .digest('hex');
  
  return {
    'X-Pelago-Timestamp': timestamp.toString(),
    'X-Pelago-Signature': signature
  };
}

// 使用示例
const body = { amount: 100, currency: 'USD' };
const signatureHeaders = createSignedRequest(
  'POST',
  '/v1/payments',
  body,
  apiSecret
);

fetch('https://api.pelago.tech/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Api-Secret': apiSecret,
    'Content-Type': 'application/json',
    ...signatureHeaders
  },
  body: JSON.stringify(body)
});

密钥安全最佳实践​

应当 ✅​

  • 将密钥存储在环境变量中
  • 沙盒与生产环境使用不同密钥
  • 每 90 天轮换密钥
  • 尽可能限制密钥权限

禁止 ❌​

  • 将密钥提交到版本控制系统
  • 通过不安全渠道分享密钥
  • 在开发中使用生产密钥
  • 在客户端代码中暴露密钥

密钥轮换​

定期轮换 API 密钥：

// 1. 在控制台生成新密钥
// 2. 更新环境变量
// 3. 验证新密钥可用
const test = await pelago.payments.list({ limit: 1 });

// 4. 在控制台删除旧密钥

范围密钥（企业版）​

企业账户可创建权限受限的范围密钥：

范围权限
payments:read仅查看支付
payments:write创建与管理支付
settlements:read查看结算
refunds:write处理退款
// 范围密钥示例
const pelago = new PelagoClient({
  apiKey: 'pk_live_xxxxx_scoped',
  apiSecret: 'sk_live_xxxxx',
  environment: 'production'
});

// 此密钥仅能读取支付
await pelago.payments.list(); // ✓ 有效
await pelago.payments.create({...}); // ✗ 无权限

故障排除​

常见错误​

错误原因解决方案
401 Unauthorized密钥无效或缺失检查密钥值
403 Forbidden密钥缺少权限使用正确的范围
429 Too Many Requests触发速率限制降低请求频率

下一步​