> For the complete documentation index, see [llms.txt](https://docs.hostelmate.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostelmate.co/api-documentation/authentication.md).

# API Authentication

All API requests must use HTTPS and include a valid **API key** in the `X-API-Key` header. There is no token exchange step — the API key is used directly.

***

## 1. Create an API Key

From the Dashboard: **Settings → API Keys** For the first time, click **Generate** to create your key.

You'll get:

* **API Key** (shown once — copy and store securely)

> Keep the key on your server only. Do **not** embed it in browser/mobile apps.

***

## 2. Required Headers

| Header            | Required                        | Description                                                                                    |
| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `X-API-Key`       | All requests                    | Your API key.                                                                                  |
| `Content-Type`    | All requests                    | Must be `application/json`.                                                                    |
| `Idempotency-Key` | **All POST and PATCH requests** | A unique UUID you generate per request. Prevents duplicate processing if a request is retried. |

> **`Idempotency-Key` is enforced on write operations.** Any `POST` or `PATCH` request missing this header is rejected with `400 bad_request: "Idempotency-Key header is required"`. Generate a fresh UUID v4 for each distinct operation. You can reuse the same key to safely retry a request that timed out, but using the same key with a different payload will be rejected.

**GET request example**

```bash
curl "https://api.hostelmate.co/api/v1/client/bookings" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json"
```

**POST request example**

```bash
curl "https://api.hostelmate.co/api/v1/client/payments" \
  -X POST \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"amount": "50.00", "paymentMethod": "Cash", "type": "income"}'
```

***

## 3. Rate Limits & Errors

* Default: **120 requests/minute/IP** on client path (subject to change)
* Common errors:
  * **400** `Idempotency-Key header is required` — missing header on a POST or PATCH request
  * **403** Origin not allowed (configure allowed domains)
  * **404** Endpoint not found
  * **429** Rate limited — implement exponential backoff
  * **5xx** Server error — retry with backoff

***