> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.lute.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate requests to the Shipdesk Public REST API using API Keys.

# Authentication

The Shipdesk API uses Bearer token authentication over HTTPS. All API requests must include your secret API key in the `Authorization` header.

```http theme={null}
Authorization: Bearer sd_live_YOUR_API_KEY
```

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:

| Prefix | Environment | Purpose |
| - | - | - |
| `sd_live_` | Production | Interacts with live carrier APIs, books real AWBs, and books real pickups |
| `sd_test_` | Sandbox | Exercises validation, orders, rate quotes, and simulated courier responses |

```bash theme={null}
# Example valid production key
sd_live_8f3a9e2d1c4b7a0f6e5d8c3b2a1f0e9d
```

***

## 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.

> [!WARNING]
>
> **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:

| Endpoint Group | Rate Limit |
| - | - |
| Standard Data & Orders (`GET/POST /v1/orders`) | 300 requests / minute |
| Courier Operations (`POST /v1/orders/:id/assign`) | 60 requests / minute |
| Rate & Serviceability (`POST /v1/rates`, `POST /v1/serviceability`) | 120 requests / minute |
| Label & POD Downloads (`GET /v1/orders/:id/label`) | 60 requests / minute |
| Courier Ingress Webhooks (`POST /v1/webhooks/courier/...`) | 300 requests / minute |

When a rate limit is exceeded, the API responds with `HTTP 429 Too Many Requests`:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down and retry in a few seconds."
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.