***

title: Bookings
description: 'How to use booking-related APIs in AISquare, integrated with Cal.com.'
------------------------------------------------------------------------------------

This guide explains how to use booking-related APIs in AISquare.

These APIs integrate with Cal.com for scheduling functionality.

***

## Overview

The bookings APIs allow you to:

* Retrieve configuration for Cal.com integration
* Refresh access tokens
* Retrieve user details

All endpoints are scoped to the authenticated user.

***

## Authentication

Bookings endpoints use:

* JWT authentication
* API key (where required)

***

## Get configuration

Retrieve Cal.com configuration details required for frontend integration.

### Endpoint

```
GET /api/v1/bookings/config/
```

### Access control

* Requires authentication
* Returns `401` if unauthorized

### Response

* Cal.com configuration data

***

## Token refresh and integration

Refresh the Cal.com access token or perform initial integration.

### Endpoint

```
POST /api/v1/bookings/token/refresh/
```

### Request body

* Uses `CalTokenRefreshRequest` schema

### Behavior

* Refreshes access token for existing users
* Handles initial integration for first-time users

### Response includes

* `access_token`
* `expires_in`
* `token_type`
* `refreshed` (boolean)
* `integration_status` (`created` or `existing`)
* `cal_client_id`

### Status codes

| Status | Meaning         |
| ------ | --------------- |
| `200`  | Success         |
| `400`  | Invalid request |
| `401`  | Unauthorized    |
| `500`  | Internal error  |

***

## Get user details

Retrieve Cal.com user details for the authenticated user.

### Endpoint

```
GET /api/v1/bookings/user/
```

### Access control

* Requires authentication
* Returns `404` if user not found

### Response

* User details based on `CalUser` schema

***

## Notes

* Bookings APIs are tied to Cal.com integration
* Token refresh endpoint supports both initial setup and refresh
* All endpoints require authentication

***

## When to use these endpoints

| Use case                   | Endpoint                   |
| -------------------------- | -------------------------- |
| Setup frontend integration | `/bookings/config/`        |
| Manage tokens              | `/bookings/token/refresh/` |
| Fetch user details         | `/bookings/user/`          |

***

## Related pages

* [Authentication](/docs/getting-started/authentication) — JWT and API key setup
* [Token lifecycle & session management](/docs/integration-guides/token-lifecycle-session-management) — token refresh patterns
* [Errors](/docs/reference/errors) — handle 400, 401, 500 responses
* [Support](/docs/reference/support) — get help with integration issues