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 permissions that control access:

• read — allows GET, HEAD, and OPTIONS requests
• write — allows POST, PUT, and DELETE requests

By default, new keys are granted both read and write permissions.

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