Stigg API — Auth, Transport, SDK Selection

This skill answers two questions: which Stigg surface to call, and how to authenticate against it correctly. Catalog / entitlement / subscription operations belong to their own skills (see routing in the umbrella stigg skill).

Before You Start

Per the umbrella stigg skill: search first. Stigg’s API is in active development (REST API in Public Beta at the time of writing). Use the Mintlify Stigg docs MCP / llms.txt to confirm endpoint shapes and SDK init signatures before generating code.

API Keys — The Three Types You Need to Know

Every environment is provisioned with two default keys; Scale-plan customers can also create scoped keys.

Where to find them: Stigg app → Integrations → API keys (each environment has its own set).

Full access key

Default per-environment. Unrestricted within that environment, and automatically inherits new permissions as Stigg adds capabilities. Only one full-access key per environment exists; users cannot create more. Use it as the default backend key while bootstrapping; switch to a narrower scoped key as your integration matures.

Publishable key

Designed for frontend / mobile SDKs. Read-only and immutable — its scope cannot be widened. Safe to ship in client-side code by design, but turn on client-side security hardening for production (HMAC SHA256 signed customer tokens — configure under the publishable key’s detail panel).

Never put a full-access or scoped server key in the browser, in a public repo, or in a frontend bundle. Use environment variables on the server.

Scoped keys (Scale plan)

User-created server keys with explicit, restricted permissions — the principle of least privilege in action. Create one per service / AI client / use case so a leak’s blast radius stays small. Scoped keys do not inherit future platform capabilities; new resources must be granted manually.

Custom permission scope matrix (presets when creating a scoped key):

• Full access — all read/write across the environment.
• Read only — read across all resources; no writes.
• Customers write — manage customer data.
• Subscriptions write — create/update subscriptions.
• Coupons write — manage discount/coupon logic.
• API keys read and write — manage API keys programmatically.
• Event Queue read — obtain temporary SQS event-queue credentials (read-only; this resource has no write).

Selecting write on a resource implicitly grants read on it.

Key rotation

From Integrations → API keys, open the key’s context menu (⋮) → Rotate key. Pick a grace period (Now / 1h / 24h / 3d / 7d). The old secret stays valid until the grace ends — zero-downtime rolling deploys are the design intent. Need more time? Change grace period before the old one expires.

Revocation is immediate and irreversible. Switch all services to the new key first.

Full reference: references/auth.md.

Pick the Right Transport

Decision flowchart with edge cases: see stigg/references/decision-tree.md. SDK selection (Node + React canonical, raw HTTP for non-Node runtimes): references/sdk-selection.md.

REST API — Quick Reference

• Base URL: https://api.stigg.io/api/v1
• Auth header: X-API-KEY: <YOUR_SERVER_KEY>
• Content-Type: application/json for bodies.
• Idempotency: add Idempotency-Key: <unique-id> to POSTs (cached 24h). Repeated calls with the same key return the cached response.
• Pagination: cursor-based. Query params: limit (default 20, max 100), starting_after, ending_before. Response includes data[], has_more, next_cursor.
• Filtering: resource-specific query params. Enum-valued filters take the underlying enum symbol (uppercase), and most list endpoints accept comma-separated values for multi-value filtering. Examples: ?email=user@example.com, ?status=ACTIVE,IN_TRIAL, ?pricingType=PAID. Date fields accept range operators (?createdAt[gte]=2026-01-01T00:00:00Z).
• Errors: standard HTTP codes with a structured body.

# 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": "billing@acme.com" }'

Money amounts — full dollars, not cents

Critical for anyone coming from Stripe: Stigg expresses monetary amounts as full dollars / units of the currency, not minor units. 49 means $49.00, not $0.49. 3990 means $3,990, not $39.90.

Stripe convention is the opposite (amounts in the smallest unit — cents for USD). Don’t multiply by 100 when handing values to Stigg, and don’t divide by 100 when reading them back. This applies to plan prices, charge amounts, cost_basis on credit grants, the subtotal / total / discount / tax fields on invoice previews — every monetary field.

Error semantics

Two REST gotchas worth knowing up front (re-confirm on the page in case they change):

• GET /api/v1/subscriptions does not include subscriptionEntitlements for each item — too expensive at scale. Use GET /api/v1/subscriptions/{id} for the detailed entitlements.
• subscriptionEntitlements on a single subscription is the overrides only, not the full set inherited from the plan. To get the full plan entitlements, call GET /api/v1/plans/{planId}/entitlements.

GraphQL API — Quick Reference

• Endpoint: https://api.stigg.io/graphql
• Auth header: X-API-Key: <YOUR_SERVER_KEY>
• When: keep GraphQL for existing integrations or queries REST hasn’t surfaced yet. Prefer REST for new work.

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 } } } }"}'

SDKs — Initialization Snippets

Always pick the SDK matching your runtime. Full matrix: references/sdk-selection.md.

Backend (Node) — @stigg/node-server-sdk:

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

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

Frontend (React) — @stigg/react-sdk:

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

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

Vanilla JS frontend uses @stigg/js-client-sdk (synchronous Stigg.initialize(...) + await client.waitForInitialization()). Other runtimes (Python, Go, Java, Ruby, .NET, Sidecar, Vue, Embed) — see references/sdk-selection.md for a brief and the link out to docs.stigg.io. The auto-generated REST-based TypeScript SDK (@stigg/typescript) is currently in beta; keep using @stigg/node-server-sdk until it reaches GA.

Rate Limits

Stigg enforces per-environment, per-endpoint rate limits. Production hot paths must handle 429 with backoff. The current limits and the “Using Stigg at Scale” guidance live at docs.stigg.io — references/rate-limits.md summarizes the operating principles.

Auth Failures — Quick Diagnosis

When NOT to Use This Skill

• Building a paywall / customer portal UI — use stigg-widgets.
• Modeling features / plans / addons — use stigg-pricing-modeling.
• Deciding between event-style and measurement-style usage reporting — use stigg-entitlements.
• First-time MCP install — use stigg-mcp.

Common Mistakes