Getting Started

Everything you need to authenticate, make your first API call, and start building with the SpireStock REST API.

Prerequisites

• An active SpireStock workspace with admin or developer access.
• An API key, created from the dashboard under Developer → API Keys. Creating one requires workspace administrator access.
• A tool for making HTTP requests — cURL, Postman, or any HTTP client library.

Base URL

All API endpoints are served from a single base URL. Every path referenced in this documentation is relative to:

https://api.spirestock.com/api/v1

For example, the full URL for listing orders would be https://api.spirestock.com/api/v1/orders.

Authentication

SpireStock accepts two credentials. Which one you want depends on whether a browser is involved.

Authenticating with an API key

Create a key in the dashboard under Developer → API Keys, or with the API itself while signed in as an administrator:

curl -X POST https://api.spirestock.com/api/v1/developer/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse sync",
    "scopes": "read,orders",
    "expires_in_days": 90
  }'

{
  "response_code": 201,
  "message": "API key created. Save this key — it won't be shown again.",
  "data": {
    "id": 3,
    "key": "df_9f3a1c7e2b8d4a6f0c5e1b7a3d9f2e4c6a8b0d2f4e6a8c0b2d4f6a8c0e2b4d6f",
    "name": "Warehouse sync",
    "key_prefix": "df_9f3a1c",
    "scopes": "read,orders",
    "expires_at": "2026-11-16T00:00:00.000Z"
  }
}

Send it on every request as a header:

X-API-Key: df_9f3a1c7e2b8d...

Scopes

A key’s scopes string mixes two kinds of token: actions (read, write) and optional resources (orders, users, products, …). read permits GET and HEAD; write permits every method and implies read. Name no resource and the key reaches every endpoint it is allowed to; name one or more and it is confined to those.

Authenticating with a session token

If you are building something a person signs into, exchange their credentials for a JWT. The request must carry a turnstile_token from the Turnstile widget on your page:

curl -X POST https://api.spirestock.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "User-Agent: AcmeIntegration/1.0" \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD",
    "turnstile_token": "TOKEN_FROM_THE_TURNSTILE_WIDGET"
  }'

{
  "response_code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Developer",
    "official_email": "[email protected]",
    "role_name": "Admin",
    "user_type": 0,
    "organization_id": 5,
    "organization_name": "Acme Dairy"
  },
  "workspace": {
    "workspace_id": "ws_x9y8z7",
    "slug": "acme-dairy",
    "display_name": "Acme Dairy",
    "plan": "professional",
    "status": 1
  }
}

Include the token in the Authorization header using the Bearer scheme:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Set a User-Agent

The API rejects requests whose User-Agent is missing, shorter than 10 characters, or matches a known scraping tool. Several HTTP clients trip this by default:

curl https://api.spirestock.com/api/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "User-Agent: AcmeIntegration/1.0"

const res = await fetch("https://api.spirestock.com/api/v1/orders", {
  headers: {
    "X-API-Key": process.env.SPIRESTOCK_API_KEY,
    "User-Agent": "AcmeIntegration/1.0",
  },
});

import requests

session = requests.Session()
session.headers.update({
    "X-API-Key": os.environ["SPIRESTOCK_API_KEY"],
    "User-Agent": "AcmeIntegration/1.0",
})

Your First Request

With a key in hand, fetch a list of orders from your workspace. Keep the key in an environment variable — never in source control.

curl https://api.spirestock.com/api/v1/orders \
  -H "X-API-Key: $SPIRESTOCK_API_KEY"

const res = await fetch("https://api.spirestock.com/api/v1/orders", {
  headers: {
    "X-API-Key": process.env.SPIRESTOCK_API_KEY,
  },
});

const { data, pagination } = await res.json();
console.log(data);  // Array of order objects
console.log(pagination.total);

import os
import requests

res = requests.get(
    "https://api.spirestock.com/api/v1/orders",
    headers={"X-API-Key": os.environ["SPIRESTOCK_API_KEY"]},
)

result = res.json()
print(result["data"])  # List of order objects
print(result["pagination"]["total"])

Every request is scoped to the organization the key belongs to. There is no tenant parameter to pass and no way to reach another workspace’s data.

Rate Limits

To ensure fair usage across all tenants, the API enforces rate limits on a per-IP or per-token basis. When a limit is exceeded the API responds with 429 Too Many Requests.

Error Handling

The API uses standard HTTP status codes. Errors include a JSON body with a response_code matching the HTTP status and a human-readable message field.

{
  "response_code": 400,
  "message": "Validation failed"
}

Next Steps

Now that you can authenticate and make requests, explore further:

• API Reference — Full endpoint documentation with request/response schemas.
• Webhooks — Receive real-time event notifications for orders, users, and payments.
• SDKs — Official client libraries for Node.js, Python, and cURL examples.