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

# Authentication

> Authenticate LightSwap API requests with backend-only API keys and learn where those credentials must not be exposed.

Every API request must include your API key in the `x-api-key` header.

```http theme={null}
x-api-key: <api_key>
```

API keys are backend credentials. Keep them in server-side configuration, secret storage, or your deployment platform's encrypted environment variables.

<Warning>
  Do not expose API keys in browser JavaScript, mobile apps, public repositories, screenshots, analytics events, or client-side error logs.
</Warning>

## Rate limits

API keys have a configured request limit. If you exceed it, the API returns `429 rate_limited`.

The response includes a `Retry-After` header when a retry delay is available.

```http theme={null}
Retry-After: 30
```

Wait at least that many seconds before retrying.

## Error responses

Authentication errors use the shared error shape.

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid.",
    "details": {}
  },
  "requestId": "req_123"
}
```

Common authentication errors:

| Code               | Meaning                                        |
| ------------------ | ---------------------------------------------- |
| `invalid_api_key`  | The key is missing or invalid.                 |
| `inactive_partner` | API access is disabled.                        |
| `rate_limited`     | The key exceeded its configured request limit. |

## Order attribution

Use optional `externalId` and `customerId` on `POST /quote` to connect a LightSwap quote and swap to your own order or user record.

Use canonical lowercase network values in API requests. For example, send `bitcoin` and `tron`.

Treat `externalId` as your primary reference. Use one stable value per order and keep it from quote creation through support and reconciliation.

```json theme={null}
{
  "customerId": "u_123",
  "externalId": "order-123",
  "from": {
    "network": "bitcoin",
    "token": "BTC",
    "amount": "0.01"
  },
  "to": {
    "network": "tron",
    "token": "USDT"
  }
}
```

Recommended practice:

* always set `externalId` on quote creation
* keep the same `externalId` when you store the resulting swap ID
* use `externalId` first when you contact LightSwap about an existing order
* use `customerId` when you want the swap payload to carry your own user reference