API Fundamentals

Skunivo public API requests are scoped to a customer organization and authenticated with API keys.

The public API is versioned under /v1:

GET /v1/organizations/{organizationId}/balances

Build integrations against the public organization API and the public OpenAPI contract. Do not depend on internal admin routes, human session cookies or private panel contracts.

Authentication

Send API keys as bearer tokens:

Authorization: Bearer skv_test_...

API keys belong to one organization and one environment. Do not rely on human session cookies, admin routes or private panel contracts for public integrations.

Use skv_test_... keys for test environments and skv_live_... keys for live environments. API keys resolve their own environment, so API key requests do not need X-Skunivo-Environment.

Request IDs

Every request should include a request id:

X-Request-Id: req_...

Request ids make retries, logs and support investigations easier to correlate. The SDK creates request ids automatically when one is not provided.

Idempotency

Write operations should include:

Idempotency-Key: product-demo-001

Use one key per logical write. Reuse it only for a retry of the exact same request after a timeout or transient failure.

If a key is reused with a different payload, Skunivo returns IDEMPOTENCY_CONFLICT.

Scopes

Common inventory scopes:

inventory:read for list and read operations.
inventory:write for create, update and operational inventory actions.

Missing scopes return a structured FORBIDDEN error.

Rate Limits

Rate limits are applied to protect the platform and keep integrations predictable. When a request is limited, Skunivo returns RATE_LIMITED with rate limit headers and Retry-After when available.

Client integrations should retry with exponential backoff, respect Retry-After and keep requestId in logs.

Structured Errors

Errors use a stable shape:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope.",
    "requestId": "req_123",
    "details": {
      "requiredScope": "inventory:write"
    }
  }
}

Common codes include VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, IDEMPOTENCY_CONFLICT, INSUFFICIENT_STOCK, CONCURRENCY_CONFLICT, RATE_LIMITED and INTERNAL_ERROR.