Authentication

Secure access to the Spwig API using API keys, tokens, or session authentication.

Overview

The Spwig API supports multiple authentication methods to accommodate different use cases. Most endpoints require authentication, but some (like product catalog browsing) are publicly accessible.

Method	Use Case	Header
Token Auth	Server-to-server integrations, mobile apps	`Authorization: Token <key>`
Session Auth	Browser-based apps, admin panel	Cookies (automatic)
No Auth	Public product catalog, store info	None required

Token Authentication

API Token

Token authentication is the recommended method for server-to-server integrations, scripts, and mobile applications. Include your API key in the Authorization header of every request.

Header Format

Authorization: Token YOUR_API_KEY

Example Request

curl -X GET "https://your-store.com/api/v1/orders/" \
  -H "Authorization: Token sk_live_abc123def456" \
  -H "Content-Type: application/json"

Example Response (Unauthorized)

{
  "detail": "Invalid token."
}

Keep your API key secret! Never expose API keys in client-side JavaScript, public repositories, or browser network requests. Use environment variables and server-side proxies.

Session Authentication

Session Cookies

Session authentication uses Spwig session cookies and is suitable for browser-based applications where users are logged in. The session is established when a user logs in through the standard login endpoint.

Login Flow

# 1. Obtain CSRF token (GET request first)
GET /api/v1/auth/csrf/

# 2. Login with credentials
POST /api/v1/auth/login/
Content-Type: application/json
X-CSRFToken: <csrf_token>

{
  "email": "[email protected]",
  "password": "your_password"
}

Subsequent Requests

After login, include the CSRF token in state-changing requests:

POST /api/v1/cart/items/
Content-Type: application/json
X-CSRFToken: <csrf_token>
Cookie: sessionid=<session_cookie>

{
  "variant_id": 123,
  "quantity": 1
}

Public Endpoints

These endpoints are accessible without authentication:

Endpoint	Description
`GET /api/v1/products/`	List products in the catalog
`GET /api/v1/products/{id}/`	Get product details
`GET /api/v1/categories/`	List product categories
`GET /api/v1/store/`	Get store information
`GET /api/v1/pages/`	List CMS pages
`POST /api/v1/auth/register/`	Customer registration
`POST /api/v1/auth/login/`	Customer login

Rate Limiting: Public endpoints may have lower rate limits than authenticated requests. See Rate Limiting for details.

API Key Management

Creating API Keys

Log in to your Spwig admin panel
Navigate to Settings → API → API Keys
Click Create New Key
Enter a descriptive name (e.g., "Mobile App", "ERP Integration")
Copy and securely store the generated key

One-Time Display: API keys are shown only once at creation. Store them immediately in a secure location like a password manager or secrets vault.

Key Naming Conventions

API keys follow a predictable format:

sk_live_* — Production keys with full access
sk_test_* — Test keys (if test mode is enabled)

Revoking Keys

If a key is compromised, revoke it immediately from the admin panel. Revoked keys stop working instantly. Create a new key and update your integrations.

Security Best Practices

Do

Use environment variables — Store API keys in .env files or your platform's secrets manager
Use HTTPS — All API requests must use HTTPS. HTTP requests will be rejected.
Rotate keys periodically — Generate new keys every 90 days as a precaution
Use separate keys per integration — Makes revocation easier if one is compromised
Log authentication failures — Monitor for brute-force attempts

Don't

Commit keys to version control — Even private repos can leak
Expose keys in client-side code — Use a backend proxy instead
Share keys between environments — Use different keys for dev/staging/production
Log full API keys — Log only the last 4 characters for debugging

Example: Secure Environment Setup

# .env file (never commit this!)
SPWIG_API_KEY=sk_live_abc123def456
SPWIG_STORE_URL=https://your-store.com

# Python usage
import os
import requests

api_key = os.environ.get('SPWIG_API_KEY')
store_url = os.environ.get('SPWIG_STORE_URL')

response = requests.get(
    f'{store_url}/api/v1/orders/',
    headers={'Authorization': f'Token {api_key}'}
)

Next Steps: Learn about Error Handling or explore the API Reference.