> For the complete documentation index, see [llms.txt](https://mobile-calendar.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobile-calendar.gitbook.io/v1/overview/authentication.md).

# Authentication

## Overview

The **Mobile Calendar API** uses **OAuth 2.0 Client Credentials Flow** for secure, server-to-server authentication

Each integration receives a **client ID** and **client secret**, which are used to obtain an access token.\
Tokens are **short-lived** (valid for 3600 seconds / 1 hour) and must be generated new before expiration.

## 1. Requesting an Access Token

### Endpoint

POST **/v1/public/auth/token**\
Content-Type: **application/json**

### Request Body

```json
{
  "clientId": "user123_438ehs833s32...",
  "clientSecret": "47yd47r39y4r34ruj9384..."
}
```

### Successful Response

```json
{
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJh...",
    "expires_in": 3600,
    "scope": [
        "reservations.read",
        "reservations.create",
        "reservations.update",
        "locks.read",
        "locks.create",
        "locks.update",
    ],
    "meta": {
        "ruid": "96ee294f-be6d-490e-adb5-bdb4c6a8b2d9"
    }
}
```

### Error Response

```json
{
    "type": "https://mobile-calendar.com...",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Invalid credentials",
    "instance": "/v1/public/auth/token",
    "ruid": "7f80f1b4-a44b-4345-b383-7d0a937b4411"
}
```

## 2. Using the Token

Include the access token in every authorized request using the `Authorization` header:

```markup
Authorization: Bearer {access_token}
```

The token grants access only to the scopes specified during creation. Once expired, a new token must be generated using the same credentials.

{% hint style="warning" %}
Tip: It is recommended to refresh your token a few minutes before it expires to ensure uninterrupted API access.
{% endhint %}

## 3. Token Lifetime

* Access token validity: **3600 seconds (1 hour)**
* No refresh token is provided
* To renew, call `/v1/public/auth/token` again with your credentials
* Expired tokens will result in a **401 Unauthorized** response

## 4. Scopes

Scopes define what actions your integration can perform. When requesting an access token, your client credentials are mapped to specific scopes assigned by the administrator.

### Available Scopes

| Scope                    | Description                       |
| ------------------------ | --------------------------------- |
| **reservations.read**    | Retrieve reservation data         |
| **reservations.create**  | Create new reservations           |
| **reservations.update**  | Update existing reservations      |
| **reservations.delete**  | Delete reservations               |
| **reservations.restore** | Restore deleted reservations      |
| **locks.read**           | Read lock device data             |
| **locks.create**         | Add new lock devices              |
| **locks.update**         | Update existing locks             |
| **locks.delete**         | Remove lock devices               |
| **rooms.read**           | List and view rooms               |
| **rooms.create**         | Create rooms                      |
| **rooms.update**         | Modify room details               |
| **rooms.delete**         | Delete rooms                      |
| **roomTypes.read**       | Read room type definitions        |
| **clients.read**         | Access client information         |
| **clients.create**       | Add new clients                   |
| **clients.update**       | Update client data                |
| **clients.delete**       | Remove clients                    |
| **pricing.read**         | Retrieve pricing information      |
| **availability.read**    | Retrieve availability information |
| **rates.read**           | Retrieve rate plans and rate data |
| **sources.read**         | Retrieve reservation source data  |
| **invoices.read**        | Retrieve invoices                 |
| **invoices.create**      | Create invoices                   |
| **invoices.update**      | Modify invoices                   |
| **invoices.delete**      | Delete invoices                   |

Scopes can be combined based on your API account configuration.

## 5. IP Address Restrictions

Each API account can be **restricted to specific IP addresses**.\
Requests coming from unauthorized IPs are rejected with:

**HTTP 403 Forbidden**

Example configuration:

Allowed IPs: 203.0.113.0, 198.51.100.10

This feature enhances security and prevents misuse of stolen credentials.

## 6. Security Best Practices

{% hint style="warning" %}

* Always use **HTTPS** — unsecured connections are blocked.
* Store your **clientId** and **clientSecret** securely (never in frontend or mobile apps).
* **Rotate credentials** periodically.
* **Cache** and **reuse** the access token until it expires.
* **Renew** tokens proactively (e.g., 5 minutes before expiration).
* Use the returned **`ruid`** for request tracing.
* Restrict access to **only the necessary scopes and IPs**.
* Validate all webhook signatures to verify authenticity.
  {% endhint %}

## 7. Example Integration Flow

{% stepper %}
{% step %}

### Obtain credentials

Obtain credentials (`clientId`, `clientSecret`) from your Mobile Calendar account.
{% endstep %}

{% step %}

### Request an access token

Request an access token via `/v1/public/auth/token`.
{% endstep %}

{% step %}

### Store the access token

Store the `accessToken` temporarily (cache or memory).
{% endstep %}

{% step %}

### Use the token

Use it in all subsequent API requests:

```bash
curl -X GET https://api.mobile-calendar.com/v1/reservations \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"
```

{% endstep %}

{% step %}

### Renew the token

Renew the token before expiration.
{% endstep %}

{% step %}

### Handle unauthorized errors

Handle 401 errors by re-authenticating automatically.
{% endstep %}

{% step %}

### Logging

Log all responses including `ruid` for audit and debugging purposes.
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mobile-calendar.gitbook.io/v1/overview/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.