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

# Overview

> Core integration concepts including environments, authentication, rate limits, idempotency, error handling, and operational best practices for secure and reliable Travelbase API integrations.

[//]: # "<img"

[//]: # "    src=\"/images/travel-base-technical.png\""

[//]: # "    alt=\"Travelbase platform overview showing offer discovery, order management, ticket issuance, wallet operations, and webhook integrations\""

[//]: # "    className=\"mt-6 mb-8 rounded-xl border\""

[//]: # "/>"

## Tenant API Overview

The Travelbase Tenant API provides secure, programmatic access to Travelbase’s travel infrastructure, enabling businesses to discover offers, manage orders, issue tickets, manage wallets, and receive real-time webhook events.

It is designed for reliable server-to-server integrations and supports the complete travel booking lifecycle, allowing organizations to integrate travel operations directly into their applications and workflows.

<CardGroup cols={2}>
  <Card title="Sandbox URL" icon="flask">
    `https://sandbox.travelbase.ai`

    Isolated environment for development and testing.
  </Card>

  <Card title="Production URL" icon="bolt">
    Available in your Travelbase Business Dashboard under **Settings → API Keys**

    Used for real-world operations and live transactions.
  </Card>
</CardGroup>

<Note>
  The sandbox environment is fully isolated. Data created here does not affect your production environment or live
  billing.
</Note>

***

## Authentication

All API requests must be authenticated using either an API key or a bearer token.

<Tabs>
  <Tab title="API Key (Recommended)">
    Use API keys for secure, server-to-server integrations.

    ```http theme={null}
    x-api-key: tb_live_xxxxxxxxxxxxxxxxx
    ```

    <Tip>
      API keys provide stable, long-lived authentication and are ideal for backend systems.
    </Tip>
  </Tab>

  <Tab title="Bearer Token">
    Use bearer tokens when acting on behalf of a signed-in dashboard user.

    ```http theme={null}
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    ```
  </Tab>
</Tabs>

<Card title="Security Best Practices" icon="shield-check">
  **Managing API Keys:** Keys can be created and rotated in the dashboard under **Settings → API Keys**.

  <Warning>
    Never expose API keys in client-side applications (web, mobile, or public code). Always store keys securely in
    backend systems or secret managers.
  </Warning>
</Card>

***

## Rate Limits

The API enforces rate limits to ensure system stability and fair usage across all tenants.

<Card title="Default Rate Limit" icon="gauge">
  **120 requests per minute** per API key.
</Card>

If a request exceeds the limit, the API returns a `429 Too Many Requests` status code.

<Tip>
  Implement retry logic using **exponential backoff** to safely handle rate limit responses and minimize service
  disruptions.
</Tip>

***

## Error Handling

Errors are returned using standard HTTP status codes and structured JSON responses to help you debug quickly.

### Error Response Format

```json theme={null}
{
        "success": false,
        "statusCode": 400,
        "errorCode": "TB_AUTH_101",
        "message": "Invalid API key",
        "fault": "client",
        "retryable": true,
        "suggestedAction": "verify your API key and try again",
        "reason": "Invalid API key",
        "environment": "sandbox",
        "apiVersion": "1.0.0"
    }
```

### Validation Errors

Validation failures may include additional field-level details to help users correct their input:

```json theme={null}
{
    "success": false,
    "status": "error",
    "statusCode": 400,
    "errorCode": "TB_VAL_302",
    "message": "Validation failed",
    "fault": "client",
    "retryable": true,
    "reason": [
        {
            "field": "email",
            "message": "Required"
        },
        {
            "field": "password",
            "message": "Required"
        }
    ],
    "apiVersion": "1.0.0"
}
```

# API Reference & Best Practices

Understanding how to handle responses and ensure data integrity is crucial for a smooth integration.

***

## HTTP Status Codes

| Code    | Meaning               | Description                                              |
| :------ | :-------------------- | :------------------------------------------------------- |
| **200** | Success               | The request was successful.                              |
| **201** | Resource Created      | A new resource has been successfully created.            |
| **400** | Invalid Request       | The request was unacceptable (e.g., missing parameters). |
| **401** | Authentication Failed | No valid API key provided.                               |
| **403** | Forbidden             | The API key does not have permissions for this resource. |
| **404** | Resource Not Found    | The requested resource doesn't exist.                    |
| **429** | Rate Limit Exceeded   | Too many requests hit the API too quickly.               |
| **500** | Internal Server Error | Something went wrong on our end.                         |

<Warning>
  **CRITICAL:** Always check the **HTTP status code** to determine success or failure before parsing the response
  body. Do not rely solely on the response content.
</Warning>

***

## Idempotency

Idempotency prevents duplicate resource creation caused by retries or network interruptions. Include an idempotency key when performing write operations (**POST** or **PUT**).

```http theme={null}
Idempotency-Key: <unique_uuid>

```

<Note>
  Idempotency Guarantee: If a request with the same key is received multiple times, the API will return the original
  response instead of creating duplicate resources. Use UUID v4 for these keys.
</Note>

## Next Steps

Explore our guides to start building your integration.

<CardGroup cols={3}>
  <Card title="Tenants" icon="users" href="/tenant-api/tenant">
    Manage organizations and sub-accounts.
  </Card>

  <Card title="Wallets" icon="wallet" href="/tenant-api/wallet">
    Handle balances, funds, and transactions.
  </Card>

  <Card title="Locations" icon="map-pin" href="/tenant-api/locations">
    Manage physical and virtual service areas.
  </Card>

  <Card title="Offers" icon="tag" href="/tenant-api/offers">
    Search available travel offers and pricing.
  </Card>

  <Card title="Orders" icon="cart-shopping" href="/tenant-api/orders">
    The full flow for creating and managing orders.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/tenant-api/webhooks">
    Receive real-time notifications for event updates.
  </Card>
</CardGroup>