API Reference

Integrate with PROIGN using our REST API. All endpoints require authentication and are scoped to specific tenants.

Base URLs

All modules are accessed through the unified gateway with path-based routing:

# Gateway URL pattern
https://app.proign.com/[tenant]/[module]/api/...

# Examples:
https://app.proign.com/canik/fulfillment/api/orders
https://app.proign.com/canik/rewards/api/points
https://app.proign.com/canik/qr/api/codes

# Platform endpoints (auth, tenants)
https://www.proign.com/api/...

Authentication

All API requests require JWT authentication via cookie. The token is set during login:

Cookie: proign_token=<jwt_token>

# JWT payload structure
{
  "sub": "user_id",
  "email": "user@example.com",
  "name": "User Name",
  "tenants": [
    {
      "id": "tenant_id",
      "slug": "tenant-slug",
      "name": "Tenant Name",
      "role": "admin",
      "modules": ["fulfillment", "rewards"],
      "userModules": ["fulfillment", "rewards"]
    }
  ]
}

Learn more about authentication →

Request Format

All requests must include Content-Type: application/json
Request bodies should be valid JSON
Tenant slug is always part of the URL path

Response Format

# Success response
{
  "data": { ... },
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0
  }
}

# Error response
{
  "error": "Error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid input
`401`	Unauthorized - Missing or invalid token
`403`	Forbidden - No access to resource
`404`	Not Found
`429`	Rate Limited
`500`	Server Error

Rate Limiting

API requests are rate limited per tenant. Limits vary by endpoint category:

Category	Limit	Examples
Read operations	100 req/min	GET orders, list products, view points
Write operations	30 req/min	Create order, update stock, send email
Auth operations	5 req/min	Login, register, password reset
File uploads	10 req/min	SDS sheets, document signing, attachments

When rate limited, the API returns 429 with a Retry-After header indicating how many seconds to wait before retrying.

Pagination

All list endpoints support cursor-based pagination via limit and offset query parameters:

# First page
GET /api/{tenant}/fulfillment/orders?limit=50&offset=0

# Second page
GET /api/{tenant}/fulfillment/orders?limit=50&offset=50

# Response includes pagination metadata
{
  "data": [...],
  "pagination": {
    "total": 247,
    "limit": 50,
    "offset": 50
  }
}

The default limit is 50 records. Maximum limit is 100 per request.

Filtering & Sorting

Most list endpoints support filtering by status, date range, and module-specific fields:

# Filter by status
GET /api/{tenant}/fulfillment/orders?status=pending

# Filter by date range
GET /api/{tenant}/fulfillment/orders?from=2026-01-01&to=2026-02-01

# Sort by field (prefix with - for descending)
GET /api/{tenant}/fulfillment/orders?sort=-created_at

# Combine filters
GET /api/{tenant}/rewards/points?dealer_id=dlr_123&from=2026-01-01&sort=-amount

Error Codes

Error responses include a machine-readable code and a human-readable message:

{
  "error": "Insufficient permissions to access this resource",
  "code": "FORBIDDEN"
}

// Common error codes:
// VALIDATION_ERROR    — Request body failed schema validation
// NOT_FOUND           — Resource does not exist or wrong tenant
// FORBIDDEN           — Valid token but insufficient role/permissions
// UNAUTHORIZED        — Missing, expired, or invalid JWT token
// RATE_LIMITED        — Too many requests, check Retry-After header
// CONFLICT            — Resource already exists or state conflict
// TENANT_INACTIVE     — Tenant subscription expired or suspended

CORS & Security

The API enforces strict security controls:

CORS — Only requests from allowed origins are accepted. Module workers restrict origins to the gateway domain.
HTTPS only — All API traffic is encrypted. HTTP requests are redirected to HTTPS.
Tenant isolation — Every query is scoped by tenant_id. Cross-tenant access is impossible by design.
Input validation — All request bodies are validated with Zod schemas before processing.
Webhook signatures — Outbound webhooks are signed with HMAC-SHA256 for payload verification.

API Sections

Authentication

JWT tokens, login flow, token refresh

Endpoints

Complete endpoint reference by module

Webhooks

Event notifications and payload formats