# API Authentication

All API requests must use HTTPS and include a valid **Bearer token**.

***

## 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. Use the API Key in Requests

Send the key via header. Include **Idempotency-Key** for write calls to avoid duplicates.

**Required/Recommended Headers**

```
X-API-Key: <your_api_key>
Content-Type: application/json
```

**Example (cURL)**

```bash
curl https://api.hostelmate.co/api/v1/client/property \
  -H "X-API-Key: hm_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "booking": {...}, "guest": {...} }'
```

***

## 4. Rate Limits & Errors (Client)

* Default: **120 requests/minute/IP** on client path (subject to change)
* Common errors:
  * **403** Origin not allowed (configure allowed domains)
  * **404** Endpoint not found
  * **429** Rate limited (use backoff)
  * **5xx** Server error (retry with backoff)

***