Authentication

All API requests must be authenticated using API keys. Include your API key in the request header to access protected endpoints.

API Key Authentication

Include your API key in the X-API-Key header with every request:

Authentication Header

X-API-Key: your_api_key_here

Generating API Keys

Before you can make API requests, you need to generate an API key from your app's settings. Follow these steps to create your first API key:

Log in to your Ultimate Custom Order Status dashboard
Navigate to Settings > API Keys
Click "Generate New API Key"
Configure the permissions for your API key
Save the API key securely (it will only be shown once)

💡 Important: Store your API key in a secure location immediately after generation. For security reasons, the key will only be displayed once and cannot be retrieved later. If you lose your API key, you'll need to generate a new one.

API Key Permissions

Each API key can be configured with specific permissions. Available permissions include:

Permission	Description
`canViewOrders`	Read access to orders
`canUpdateOrders`	Update order information and statuses
`canSendNotifications`	Send customer notifications (email, SMS, WhatsApp)
`canChangeOrderStatus`	Update order status and sub-status
`canOverrideProductChainEnforcement`	Bypass product chain enforcement rules when updating status
`canViewStatuses`	Read access to custom statuses
`canManageStatuses`	Create, update, and delete custom statuses

Rate Limiting

API requests are rate limited per API key using two separate windows:

Per-minute limit: Configurable per key (default: 60 requests/minute)
Per-day limit: Configurable per key (default: 10,000 requests/day)

Both limits must be satisfied for a request to be allowed. If either limit is exceeded, the request will be rejected with a 429 status code.

Rate limit information is included in all API response headers:

X-RateLimit-Limit-Minute: Maximum requests per minute
X-RateLimit-Remaining-Minute: Remaining in current minute
X-RateLimit-Reset-Minute: Unix timestamp (seconds) when minute resets
X-RateLimit-Limit-Day: Maximum requests per day
X-RateLimit-Remaining-Day: Remaining in current day
X-RateLimit-Reset-Day: Unix timestamp (seconds) when day resets
Retry-After: Seconds to wait before retrying (present when rate limited)

Security Best Practices

⚠️ Important Security Guidelines

Never commit API keys to version control
Store API keys in environment variables or secure key management systems
Rotate API keys regularly
Use different API keys for different environments (development, staging, production)
Immediately revoke any API keys that may have been compromised
Use the minimum necessary permissions for each API key
Monitor API usage for unusual patterns

Example Request

Here's a complete example of an authenticated API request:

Authenticated cURL Request

curl -X GET "https://ultimate-custom-order-status.app.msmtech.ca/api/v1/orders?page=1&limit=25" \
  -H "X-API-Key: sk_live_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Error Responses

401 Unauthorized

Returned when the API key is missing or invalid:

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Returned when the API key lacks required permissions:

403 Forbidden

{
  "error": "Forbidden",
  "message": "API key does not have required permission: canViewOrders"
}