4klyft API (1.0.0)

This API provides endpoints for managing:

• Catalog (PIM/DAM): products, variants, attributes, options, categories, brands, collections, assortments, and media
• Sales: orders, customers, merchants, sales channels, and channel order import
• Inventory: stock items, levels, lots, and serial units across custodians
• Warehousing & Operations: goods receipt/issue, holds, and custodian operations
• Fulfilment: fulfilment orders dispatched to third-party (3PL) providers
• Shipping: carriers, shipments, labels, tracking, returns, and proof of delivery
• Finance & Billing: payments, settlements, invoices, credit notes, tax, and subscriptions
• Integration: sales-channel connections, providers, webhooks, and catalog/order sync
• Documents: operational document generation and requests
• Storage: file/drive storage with chunked upload and signed access
• Identity & Access (IAM): authentication, users, roles, permissions, and tenants
• Platform services: notifications, scheduling, numbering, data exchange, analytics, and workspace tables & views

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Every /api/ request is rate-limited per caller — by your authenticated identity when a token is present, otherwise by client IP. The authentication endpoints (/auth/login, /auth/refresh, /auth/request-password-reset) carry stricter, IP-based limits.

Each response advertises your current budget via headers:

• X-RateLimit-Limit — the bucket size
• X-RateLimit-Remaining — tokens left in the current window
• X-RateLimit-Reset — Unix timestamp when a token next frees up

Exceeding a limit returns 429 Too Many Requests (RFC 6585) with a Retry-After header (seconds to wait). Back off and retry after the indicated delay rather than hammering the endpoint.

The API uses RFC 7807 Problem Details for error responses.

Wizard-time custodian connection validation endpoint.

POST /api/warehousing/custodians/test-connection with {type, connectionConfig}. Returns {ok, code, message} indicating whether the supplied credentials pass the per-provider validator. Phase 4 only validates structural shape; Phase 5 will round-trip against the upstream adapter API.

OAuth / API-key wizard endpoints for the three external custodian providers:

POST /api/warehousing/custodian-wizard/{provider}/auth-start POST /api/warehousing/custodian-wizard/{provider}/auth-callback GET /api/warehousing/custodian-wizard/{provider}/resources?custodianId=...

{provider} is the CustodianType key — amazon_fba, bol_fbb, or flexport. Connection testing is exposed via the existing /custodians/test-connection endpoint (passing custodianId in the connectionConfig payload).