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

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

POST request example

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

---