Authentication

API Key Authentication

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys have the form ucos_<live|test>_<32 base64url characters>, for example ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. Keep them server-side and rotate any key that appears in a log or a screenshot.

Generating API Keys

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

Managing API Keys

• The display name and description are editable at any time.
• The key material, permissions, rate limits and expiry are fixed at creation and cannot be changed afterwards.
• To change any of those, revoke the key and create a replacement. A revoked key stays listed and refuses authentication until its record is deleted.
• Rate limits are set per key at creation (defaults: 60 requests per minute and 10,000 per day) and are reported in the X-RateLimit-* response headers.
• The keys card lists the most recent requests each key served, so usage is auditable in the app.

API Key Permissions

Rate Limiting

• Per-minute limit: Set per key at creation (default: 60 requests/minute)
• Per-day limit: Set per key at creation (default: 10,000 requests/day)

A request over either limit is rejected with 429, a Retry-After header, and details.retryAfter in the body.

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

Audit Logging

• Authenticated requests log the endpoint, method, status code, response time, source address and user agent.
• A request that fails (4xx or 5xx) also records the request body and the response’s error message, so a rejected payload can be diagnosed from the log.
• A request rejected before authentication (missing or unknown key, 401) has no per-key row; the app records the attempt separately (reason, last four characters of any key presented, source and endpoint) for support.
• Both kinds of record are kept for 90 days by default and then pruned.
• A revoked or expired key that is presented is recorded as a 401 (so a retired key still in use stays visible) but does not count as a use.
• The key’s usage counter and last-used time update exactly once per authenticated request, including requests refused by a permission check or by the rate limit.

Example Request

curl -X GET "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders?page=1&limit=25" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5"

Error Responses

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

{
  "success": false,
  "error": "Insufficient permissions. Required: canViewOrders"
}

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "errors": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["status_id"],
        "message": "Required"
      }
    ]
  }
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "details": {
    "retryAfter": 30
  }
}

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}