Authentication

All API requests require a valid API key passed as a Bearer token.

API Key Format

Keys follow the format sw_live_ followed by a random string:

sw_live_a3Bf9kLm2nPq7rSt...

Creating API Keys

Generate keys from the ShipWave dashboard under Settings > API Keys.

Each key has a name for identification and access that you choose when you create it:

• Shipping API — read and write access to orders, shipments, rates, returns, and inventory (GET/HEAD/OPTIONS need read; POST/PUT/DELETE need write)
• Address verification — the address verification API (/api/v1/addresses/*). Shipping API access does not include it; check this box to use those endpoints.

A key can have both. Keys expire after one year.

Important: The full key is shown only once at creation. Store it securely — it cannot be retrieved later. Only the prefix (e.g. sw_live_a3Bf9k...) is stored for identification.

Using Your API Key

Pass the key in the Authorization header:

curl https://shipwave.app/api/v1/orders \
  -H "Authorization: Bearer sw_live_a3Bf9kLm2nPq7rSt..."

const res = await fetch("https://shipwave.app/api/v1/orders", {
  headers: {
    Authorization: "Bearer sw_live_a3Bf9kLm2nPq7rSt...",
  },
});

Permission Enforcement

The required permission is determined by the HTTP method:

If your key lacks the required permission, you'll receive a 403 FORBIDDEN error:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks \"write\" permission"
  }
}

Revoking Keys

Revoke a key from the dashboard under Settings > API Keys. Revoked keys immediately stop working and return 401 UNAUTHORIZED.

Key Expiration

Keys can optionally have an expiration date. Expired keys return 401 UNAUTHORIZED with the same generic message as invalid or missing keys:

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

Errors