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

# Authentication

> Learn how to authenticate with the WasteCheck API

# Authentication

The WasteCheck API uses API keys to authenticate requests. You can manage your API keys from the [Developer Portal](https://portal.wastecheck.co.uk).

## API Key Authentication

Include your API key in the `Authorization` header with every request:

```bash theme={null}
curl https://api.wastecheck.co.uk/v1/verify-carrier \
  -H "Authorization: Bearer wc_live_your_api_key_here"
```

## Live vs Test Keys

WasteCheck provides two types of API keys:

| Key Type | Prefix     | Purpose                                                |
| -------- | ---------- | ------------------------------------------------------ |
| Live     | `wc_live_` | Production requests, counted against quota             |
| Test     | `wc_test_` | Development and testing, returns mock data, not billed |

<Warning>
  Never expose your API keys in client-side code, public repositories, or browser requests. Always make API calls from your server.
</Warning>

## Getting Your API Key

1. Sign up at [portal.wastecheck.co.uk/signup](https://portal.wastecheck.co.uk/signup)
2. Navigate to **API Keys** in the dashboard
3. Click **Create New Key** and choose Live or Test
4. Copy the key immediately -- it is only shown once

## Rate Limiting

Rate limits are applied per API key using a sliding window. When you exceed the limit, the API returns `429 Too Many Requests` with a `Retry-After` header.

Monthly usage is tracked per API key and resets on the 1st of each billing cycle.

### Plan Limits

| Plan         | Price   | Monthly Calls | Rate Limit  |
| ------------ | ------- | ------------- | ----------- |
| Free         | £0      | 50            | 10 req/min  |
| Starter      | £29/mo  | 200           | 30 req/min  |
| Professional | £79/mo  | 1,000         | 60 req/min  |
| Business     | £249/mo | 10,000        | 120 req/min |
| Enterprise   | Custom  | Custom        | Custom      |

All plans include all endpoints. There is no feature gating between tiers.

### Rate Limit Headers

Every response includes these headers:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per minute for your plan |
| `X-RateLimit-Remaining` | Requests remaining in the current window  |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets     |
| `X-Monthly-Limit`       | Total calls allowed this billing cycle    |
| `X-Monthly-Remaining`   | Calls remaining this billing cycle        |

## Error Responses

If authentication fails, the API returns:

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is missing, invalid, or revoked.",
    "status": 401
  }
}
```

### Common Error Codes

| Code                  | HTTP | Description                                          |
| --------------------- | ---- | ---------------------------------------------------- |
| `INVALID_API_KEY`     | 401  | API key is missing, invalid, or revoked              |
| `RATE_LIMIT_EXCEEDED` | 429  | Request rate or monthly usage limit exceeded         |
| `INVALID_REQUEST`     | 400  | Request body is malformed or missing required fields |
| `INTERNAL_ERROR`      | 500  | Unexpected server error                              |