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

# Authentication

> How to authenticate with the Handled Returns API

## Authentication

All API requests require a Bearer token in the Authorization header:

```
Authorization: Bearer YOUR_API_TOKEN
```

### Getting Started

To use the Handled Returns API, you'll need:

1. **Account ID** - Your unique Handled account identifier
2. **API Token** - Your secret authentication token

### Request Headers

Include these headers with every API request:

```http theme={null}
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json
```

### Example Request

```bash theme={null}
curl -X GET \
  https://your-domain.com/api/v1/accounts/123/returns \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json'
```

### Token Security

* Keep your API token secure and never expose it in client-side code
* Rotate tokens regularly
* Use environment variables to store tokens in your applications
* Never commit tokens to version control

### Rate Limiting

API requests are subject to rate limiting:

* Returns endpoints: 1000 requests per hour
* Storefront endpoints: 100 requests per minute per IP
* Webhook endpoints: 10,000 requests per hour

Rate limit information is included in response headers:

* `X-RateLimit-Limit`
* `X-RateLimit-Remaining`
* `X-RateLimit-Reset`

### Error Responses

Failed authentication returns a 401 Unauthorized response:

```json theme={null}
{
  "error": "Unauthorized",
  "error_code": "INVALID_TOKEN",
  "details": {
    "message": "Invalid or expired API token"
  }
}
```