API Reference

RESTful API for managing customers, subscriptions, and entitlements.

Open Interactive API Docs (Swagger)

Base URL

text
https://api.stackbe.io

All API requests should be made to this base URL. HTTPS is required for all requests.

Authentication

StackBE uses API keys to authenticate requests. Include your API key in the Authorization header:

bash
curl https://api.stackbe.io/v1/customers \
  -H "Authorization: Bearer sk_live_your_api_key"

Keep your API keys secure. Never expose them in client-side code or public repositories.

Authentication Types

  • API Keys — For server-to-server requests. Created in the StackBE dashboard.
  • Session Tokens — For authenticated customer requests. Obtained via magic link auth.

Learn more about authentication

Rate Limits

API requests are rate limited to ensure fair usage:

  • 1,000 requests/minute per API key
  • 100 requests/minute per customer session

Rate limit headers are included in all responses:

text
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1704067200

Error Responses

Errors return a consistent JSON structure:

json
{
  "statusCode": 400,
  "message": "Invalid email format",
  "error": "Bad Request"
}

HTTP Status Codes

  • 200 — Success
  • 201 — Created
  • 400 — Bad Request (invalid parameters)
  • 401 — Unauthorized (invalid or missing API key)
  • 403 — Forbidden (insufficient permissions)
  • 404 — Not Found
  • 429 — Rate Limit Exceeded
  • 500 — Internal Server Error

Core Endpoints

Customers

  • GET /v1/customers
  • POST /v1/customers
  • GET /v1/customers/:id
  • PATCH /v1/customers/:id

Subscriptions

  • GET /v1/subscriptions/current
  • POST /v1/subscriptions/:id/cancel
  • POST /v1/subscriptions/:id/pause
  • POST /v1/subscriptions/:id/resume

Entitlements

  • GET /v1/entitlements
  • GET /v1/entitlements/check/:feature

Checkout

  • POST /v1/checkout/session

Auth (Customer)

  • POST /v1/apps/:appId/auth/magic-link
  • POST /v1/apps/:appId/auth/verify
  • GET /v1/apps/:appId/auth/session

For complete endpoint documentation with request/response examples, see the interactive Swagger docs.