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.
A valid email and password for an account within that workspace.
A tool for making HTTP requests — cURL, Postman, or any HTTP client library.

💡

Don't have a workspace yet?

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 uses JWT Bearer tokens for authentication. Obtain a token by sending your credentials to the login endpoint, then include that token in the Authorization header of every subsequent request.

Step 1 — Obtain a Token

Send a POST request to /auth/login with your email and password:

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

Response (200 OK)
{
  "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
  }
}

Step 2 — Use the Token

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

⚠️

Token Expiry & Security

Tokens expire after 15 days. When you receive a 401 Unauthorized response, re-authenticate by calling /auth/login again. Logging out or changing your password immediately invalidates all active tokens.

🚨

Token Storage Best Practices

Never store JWT tokens in localStorage or sessionStorage — they are accessible to any JavaScript running on the page (XSS-vulnerable). Instead:

Server-side apps: Store tokens in memory or encrypted server-side sessions.
Browser apps: Use httpOnly cookies set by your backend proxy, or keep tokens in memory only (they will be lost on page refresh, which is the safer trade-off).
Never include tokens in URLs, log files, or error reporting payloads.

Your First Request

Once authenticated, try fetching a list of orders from your workspace. The examples below show the same request in multiple languages:

GET /orders

curl https://api.spirestock.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_TOKEN"

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.

Endpoint Group	Limit	Window
`POST /signup/register`	5 requests	Per hour
`POST /auth/login`	20 requests	Per 15 minutes
General endpoints	120 requests	Per minute
General endpoints	2,000 requests	Per hour
Export endpoints	5 requests	Per minute
Report endpoints	20 requests	Per minute

💡

Rate-limit headers

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can proactively throttle your 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.

Error response example
{
  "response_code": 400,
  "message": "Validation failed"
}

Status Code	Meaning	Common Cause
`400`	Bad Request	Invalid or missing request body fields
`401`	Unauthorized	Missing or expired JWT token
`403`	Forbidden	Insufficient permissions for the requested resource
`404`	Not Found	Resource does not exist or belongs to another workspace
`429`	Too Many Requests	Rate limit exceeded — back off and retry
`500`	Internal Server Error	Unexpected server-side failure — contact support if it persists

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.