stigg-api

Stigg API — 身份验证、传输方式、SDK 选择

本技能解答两个问题：应调用哪个 Stigg 接口，以及如何正确进行身份验证。目录、权益和订阅操作属于各自的技能（请参阅总览 stigg 技能中的路由说明）。

开始之前

根据总览 stigg 技能的说明：先搜索。Stigg 的 API 正在积极开发中（撰写本文时，REST API 处于公开测试阶段）。生成代码前，请使用 Mintlify Stigg 文档 MCP / llms.txt 确认端点形式和 SDK 初始化签名。

需要了解的三种 API 密钥

每个环境都会配置两个默认密钥；Scale 计划客户还可以创建限定范围的密钥。

类型	前缀	存放位置	默认范围	可自定义范围？
完全访问（服务端）	server-	仅限后端	所有当前和未来权限	否（不可变）
可发布（客户端）	client-	浏览器、移动端	只读，范围有限	否（不可变）
限定范围（服务端）	server-	仅限后端	自行选择	可以，按资源设置

**查找位置：**Stigg 应用 → Integrations → API keys（每个环境都有各自的一组密钥）。

完全访问密钥

每个环境的默认密钥。在该环境中不受限制，并且随着 Stigg 添加新功能，会自动继承新权限。每个环境只能有一个完全访问密钥；用户无法创建更多密钥。集成初期可将其用作默认后端密钥；随着集成逐步成熟，再切换到范围更窄的限定范围密钥。

可发布密钥

专为前端 / 移动端 SDK 设计。该密钥为只读且不可变，无法扩大其范围。根据设计，可安全地用于客户端代码；但在生产环境中，请启用客户端安全加固（HMAC SHA256 签名的客户令牌——在可发布密钥的详情面板中配置）。

切勿将完全访问密钥或限定范围的服务端密钥放入浏览器、公开仓库或前端包中。请在服务端使用环境变量。

限定范围密钥（Scale 计划）

由用户创建、具有明确受限权限的服务端密钥——这是最小权限原则的实际应用。请为每个服务 / AI 客户端 / 用例创建一个密钥，缩小密钥泄露造成的影响范围。限定范围密钥不会继承平台未来新增的功能；必须手动授予对新资源的权限。

自定义权限范围矩阵（创建限定范围密钥时的预设选项）：

• 完全访问 — 在整个环境中拥有所有读写权限。
• 只读 — 可读取所有资源；不可写入。
• 客户写入 — 管理客户数据。
• 订阅写入 — 创建 / 更新订阅。
• 优惠券写入 — 管理折扣 / 优惠券逻辑。
• API 密钥读取和写入 — 以编程方式管理 API 密钥。
• 事件队列读取 — 获取临时 SQS 事件队列凭证（只读；此资源不支持写入）。

对某项资源选择写入权限时，会自动授予该资源的读取权限。

密钥轮换

前往 Integrations → API keys，打开密钥的上下文菜单（⋮）→ Rotate key。选择宽限期（Now / 1h / 24h / 3d / 7d）。旧密钥会在宽限期结束前保持有效——其设计目的在于实现零停机滚动部署。需要更多时间？请在旧密钥过期前Change grace period。

撤销会立即生效且不可撤销。请先将所有服务切换到新密钥。

完整参考： references/auth.md。

选择合适的传输方式

接入方式	适用场景
Node SDK (@stigg/node-server-sdk)	Node / TypeScript 上的生产热路径。后端的默认选择。 其他后端运行时（Python、Go、Java、Ruby、.NET、Sidecar）也提供 SDK — 详见 docs.stigg.io；模式类似，但具体字段名可能有所不同。
前端 SDK (@stigg/react-sdk for React / Next.js; @stigg/js-client-sdk for vanilla JS)	在浏览器中渲染付费墙、客户门户或检查权益。
REST API (https://api.stigg.io/api/v1)	你的语言没有 SDK；轻量级服务端代理；需要明确控制。
GraphQL API (https://api.stigg.io/graphql)	已有 GraphQL 集成，或 REST API 尚未提供的查询。
Stigg MCP 服务 (https://mcp.stigg.io)	AI 辅助开发。详见 stigg-mcp。
Stigg CLI（Go 二进制文件 — brew install stiggio/tools/stigg；仓库：https://github.com/stiggio/stigg-cli）	脚本、CI/CD。仅选择启用 — 默认与选择启用方式详见 stigg-mcp/references/cli-vs-mcp.md。

包含边缘情况的决策流程图：详见 stigg/references/decision-tree.md。SDK 选择（Node + React 为规范方式，非 Node 运行时使用原始 HTTP）：references/sdk-selection.md。

REST API — 快速参考

• 基础 URL： https://api.stigg.io/api/v1
• 身份验证标头： X-API-KEY: <YOUR_SERVER_KEY>
• Content-Type： 请求体使用 application/json。
• 幂等性： 为 POST 请求添加 Idempotency-Key: <unique-id>（缓存 24 小时）。使用同一键重复调用会返回缓存的响应。
• 分页： 基于游标。查询参数：limit（默认 20，最大 100）、starting_after、ending_before。响应包含 data[]、has_more、next_cursor。
• 筛选： 使用特定资源的查询参数。枚举值筛选器须使用底层枚举符号（大写），大多数列表端点支持用逗号分隔多个值进行筛选。示例：[email protected]、?status=ACTIVE,IN_TRIAL、?pricingType=PAID。日期字段支持范围运算符（?createdAt[gte]=2026-01-01T00:00:00Z）。
• 错误： 使用标准 HTTP 状态码和结构化响应体。

# Authenticated GET
curl -X GET "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: $STIGG_SERVER_API_KEY" \
  -H "Content-Type: application/json"

# Idempotent POST
curl -X POST "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: $STIGG_SERVER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bootstrap-customer-acme-001" \
  -d '{ "id": "customer-123", "name": "Acme Corp", "email": "[email protected]" }'

货币金额 — 使用完整金额，而非美分

对 Stripe 用户尤为重要： Stigg 以完整美元金额 / 货币单位表示货币金额，而非最小货币单位。49 表示 $49.00，而非 $0.49。3990 表示 $3,990，而非 $39.90。

Stripe 的惯例正好相反（金额以最小货币单位表示 — USD 使用美分）。向 Stigg 传值时不要乘以 100，读回值时也不要除以 100。这适用于套餐价格、收费金额、信用额度授予中的 cost_basis，以及发票预览中的 subtotal / total / discount / tax 字段 — 所有货币字段均如此。

错误语义

状态码	含义
200	成功 — 响应体包含资源
201	已创建
400	错误请求 — 参数 / 请求体无效
401	未通过身份验证 — 缺少或无效的 X-API-KEY
403	禁止访问 — 已通过身份验证，但密钥缺少所需权限范围
404	未找到
409	冲突 — 例如，订阅已存在
429	请求过多 — 详见速率限制

建议提前了解的两个 REST 注意事项（请在页面上重新确认，以防内容变更）：

• GET /api/v1/subscriptions 不会为每个项目返回 subscriptionEntitlements — 因为在大规模场景下开销过高。使用 GET /api/v1/subscriptions/{id} 获取详细权益。
• 单个订阅上的 subscriptionEntitlements 仅包含覆盖项，不包含从套餐继承的完整权益集。要获取套餐的完整权益，请调用 GET /api/v1/plans/{planId}/entitlements。

GraphQL API — 快速参考

• 端点： https://api.stigg.io/graphql
• 身份验证标头： X-API-Key: <YOUR_SERVER_KEY>
• 使用场景： 已有集成或 REST 尚未提供的查询可继续使用 GraphQL。新工作优先使用 REST。

curl -X POST https://api.stigg.io/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $STIGG_SERVER_API_KEY" \
  -d '{"query":"{ customers { edges { node { customerId name } } } }"}'

SDK — 初始化代码片段

请始终选择与运行时匹配的 SDK。完整矩阵：references/sdk-selection.md。

后端（Node）— @stigg/node-server-sdk：

import Stigg from '@stigg/node-server-sdk';

const stigg = await Stigg.initialize({
  apiKey: process.env.STIGG_SERVER_API_KEY!,
});

前端（React）— @stigg/react-sdk：

import { StiggProvider } from '@stigg/react-sdk';

<StiggProvider apiKey="<STIGG_CLIENT_API_KEY>" customerId="<LOGGED_IN_CUSTOMER_ID>">
  {children}
</StiggProvider>

原生 JavaScript 前端使用 @stigg/js-client-sdk（同步调用 Stigg.initialize(...)，然后执行 await client.waitForInitialization()）。其他运行时（Python、Go、Java、Ruby、.NET、Sidecar、Vue、Embed）——简要说明及 docs.stigg.io 的外链请参阅 references/sdk-selection.md。自动生成的基于 REST 的 TypeScript SDK（@stigg/typescript）目前仍处于 Beta 阶段；在其达到 GA 之前，请继续使用 @stigg/node-server-sdk。

速率限制

Stigg 按环境和端点实施速率限制。生产环境的热路径必须在遇到 429 时进行退避处理。当前限制和“Using Stigg at Scale”指南位于 docs.stigg.io — references/rate-limits.md 总结了操作原则。

身份验证失败 — 快速诊断

症状	可能原因	修复方法
每个请求都返回 401 Unauthenticated	请求头名称拼写错误（使用了 Authorization 而非 X-API-KEY）	请准确使用 X-API-KEY。
只有 POST 请求返回 401	缺少或错误的 Content-Type 导致网关在身份验证前拒绝请求	设置 Content-Type: application/json。
轮换密钥后返回 401	旧密钥已超过宽限期	将服务切换到新密钥。
403 Forbidden	限定范围的密钥没有访问该资源的权限	授予缺失的权限，或使用权限范围更广的密钥。
前端 SDK 显示了其他客户的数据	缺少客户端加固措施	为可发布密钥启用 HMAC 签名的客户令牌。
生产环境中的“Stigg”调用访问了沙箱	环境配置中的密钥错误	密钥绑定到特定环境 — 请核实并替换。

不要在以下情况下使用此技能

• 构建付费墙 / 客户门户 UI — 请使用 stigg-widgets。
• 建模功能 / 计划 / 附加项 — 请使用 stigg-pricing-modeling。
• 决定采用事件式还是度量式用量报告 — 请使用 stigg-entitlements。
• 首次安装 MCP — 请使用 stigg-mcp。

常见错误

错误	修复方法
在前端应用中放置 server- 密钥	请使用 client- 可发布密钥。
在所有地方硬编码完全访问权限密钥	为每个服务创建限定范围的密钥。
客户 / 订阅 POST 请求缺少 Idempotency-Key	设置该请求头 — Stigg 会缓存响应 24 小时，因此重试是安全的。
将 subscriptionEntitlements 视为完整集合	它只包含覆盖项。请使用计划端点获取完整列表。
调用 GET /subscriptions 并期待返回权益	按设计，该端点不会返回权益。请逐行使用 GET /subscriptions/{id}。
在新代码中混用 REST 和 GraphQL	选择一种（默认使用 REST）。除非有充分理由，否则不要构建混合方案。