Skip to main content

Authentication

The Shipdesk API uses Bearer token authentication over HTTPS. All API requests must include your secret API key in the Authorization header.
Requests made without an Authorization header, or with an invalid/revoked token, will be rejected with an HTTP 401 Unauthorized status.

API Key Format

Shipdesk API keys are prefixed to help identify the environment:

Managing API Keys

API keys are managed directly from the Shipdesk Web Application:
  1. Navigate to Settings (⚙) in the sidebar or top header.
  2. Click on the API & Webhooks tab (#settings-api).
  3. Click + Generate API key.
  4. Choose a descriptive name (e.g. Shopify Sync Engine, ERP Automated Dispatch) and assign a role:
    • Admin: Full access to all endpoints, assignment, pickups, and account settings.
    • Ops: Operational access to orders, shipments, pickups, and NDR actions.
    • Support viewer: Read-only access to search orders, tracking timelines, and download reports.
Secret Key Security: Your full secret key is only displayed once upon generation. Shipdesk stores only a salted SHA-256 hash in the database. If you lose your secret key, revoke it and generate a new one.

Multi-Tenant Organization Scope

Every API key is tied strictly to your organization’s workspace (org_id). When your backend makes an API call:
  • The caller’s organization is resolved from the key.
  • Your request can only read or modify records belonging to your account.
  • Row-Level Security (RLS) guarantees absolute tenant data isolation.

Rate Limits

To protect service availability and prevent courier API flooding, Shipdesk enforces IP and organization-level rate limits: When a rate limit is exceeded, the API responds with HTTP 429 Too Many Requests: