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

# Authentication & Setup

> How to authenticate with the NowBookIt IPOS Partner API, handle rate limits, and interpret errors

## Authentication methods

NowBookIt IPOS supports two authentication methods depending on the integration pattern you are using.

<Tabs>
  <Tab title="X-API-KEY (REST API)">
    All standard REST API endpoints authenticate using an `X-API-KEY` header.

    ```bash theme={null}
    curl https://{base_url}/Bookings \
      -H "X-API-KEY: your_api_key" \
      -H "Content-Type: application/json"
    ```

    **How to obtain your API key:**

    Contact your NowBookIt partner manager at [platform.integrations@nowbookit.com](mailto:platform.integrations@nowbookit.com). API keys are issued per partner per environment and are scoped to the venues linked to your app.

    <Warning>
      Keep your API key secure. Do not expose it in client-side code, public repositories, or logs. If a key is compromised, contact [platform.integrations@nowbookit.com](mailto:platform.integrations@nowbookit.com) immediately for rotation.
    </Warning>
  </Tab>

  <Tab title="HMAC Signature (Partner Inbound)">
    Partner inbound webhook endpoints use **HMAC signature authentication**. Instead of an API key, you send a signature computed over the request body and URL using a shared secret.

    **Signature header:** A custom header agreed during onboarding (e.g., `X-Partner-Signature`)

    **How to compute the signature:**

    ```javascript theme={null}
    const crypto = require("crypto");

    function computeSignature(sharedSecret, requestBody, requestUrl) {
      const payload = requestBody + requestUrl;
      return crypto
        .createHmac("sha256", sharedSecret)
        .update(payload)
        .digest("hex");
    }
    ```

    ```python theme={null}
    import hmac
    import hashlib

    def compute_signature(shared_secret: str, request_body: str, request_url: str) -> str:
        payload = (request_body + request_url).encode("utf-8")
        return hmac.new(
            shared_secret.encode("utf-8"),
            payload,
            hashlib.sha256
        ).hexdigest()
    ```

    Your partner manager will provide:

    * The exact header name to use (e.g., `X-Partner-Signature`)
    * The shared HMAC secret
    * Your `partnerName` slug used in inbound endpoint paths
  </Tab>
</Tabs>

***

## Rate limiting

The API enforces rate limits per endpoint. When you exceed the limit, you will receive a `429 Too Many Requests` response.

**Response body (429):**

```json theme={null}
{
  "message": "You may only perform this action 10 times every 1000 milliseconds"
}
```

The message indicates the exact limit and window for that endpoint. Implement **exponential backoff** when you receive a 429:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const delay = Math.pow(2, attempt) * 500; // 500ms, 1s, 2s
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after retries");
}
```

***

## Error responses

All endpoints use standard HTTP status codes. Error responses follow a consistent JSON structure.

### Status codes

| Code  | Meaning               | Common causes                                                               |
| ----- | --------------------- | --------------------------------------------------------------------------- |
| `200` | OK                    | Request succeeded                                                           |
| `201` | Created               | Resource created successfully                                               |
| `400` | Bad Request           | Missing required fields, invalid date format, venue not linked to your app  |
| `401` | Unauthorized          | Missing or invalid `X-API-KEY`                                              |
| `404` | Not Found             | Resource with the given ID does not exist                                   |
| `409` | Conflict              | Duplicate ID within the deduplication window (e.g., sale already submitted) |
| `429` | Too Many Requests     | Rate limit exceeded                                                         |
| `500` | Internal Server Error | Unexpected server error                                                     |

### 400 Bad Request — common messages

<AccordionGroup>
  <Accordion title="Venue not linked">
    ```json theme={null}
    { "message": "No Venue Subscribed to your App." }
    ```

    Your API key is valid, but the venue you are trying to access has not been linked to your partner app. Contact your NowBookIt partner manager to confirm the location mapping.
  </Accordion>

  <Accordion title="loggedInAppId error">
    ```json theme={null}
    { "message": "loggedInAppId is required" }
    ```

    The API key provided does not resolve to a known partner app. Verify you are sending the correct key in the `X-API-KEY` header.
  </Accordion>

  <Accordion title="Missing required fields">
    ```json theme={null}
    { "message": "numOfPeople is required" }
    ```

    A required request field is missing or null. Check the endpoint documentation for required fields.
  </Accordion>

  <Accordion title="Date filter validation">
    When filtering bookings by date, you must provide either `StartDate + EndDate` **or** `UpdatedFromDate + UpdatedToDate`. Mixing date types or omitting both will return no results without an error — check the [GET /Bookings](/bookings/list) docs for details.
  </Accordion>
</AccordionGroup>

### 401 Unauthorized

```json theme={null}
{
  "message": "Unauthorized"
}
```

Returned when the `X-API-KEY` header is missing or the key is invalid. Ensure the header is present on every request.

***

## Content type

For all `POST`, `PUT`, and `PATCH` requests, include the `Content-Type` header:

```
Content-Type: application/json
```

***

## Environments

NowBookIt IPOS operates in separate environments. Your partner manager will confirm which base URL to use for development vs. production.

| Environment | Notes                                                                       |
| ----------- | --------------------------------------------------------------------------- |
| Development | Safe for testing — use the `.dev.` subdomain URL provided during onboarding |
| Production  | Live venue data — use with care                                             |