> For the complete documentation index, see [llms.txt](https://docs.guestway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guestway.io/account-and-administration/api-access.md).

# API access

API access holds the tokens and webhooks that connect your own systems to the Guestway Open API.

{% hint style="info" %}
**Requirements**

* To create and delete API access tokens, you need the **Super admin** role. See [Users and roles](https://docs.guestway.io/account-and-administration/users-and-roles.md).
* To use the API, you need a partnership with Guestway and its Partnership API Key.
  {% endhint %}

Go to **Settings** → **Organization** → **API Access**. The page has three tabs: **API Access**, **Webhooks** and **Webhook Logs**. Each tab shows only when your role has access to it.

## The Guestway Open API

The Guestway Open API lets business partners connect their systems to Guestway, server to server. It gives access to:

* Organization data: basic information about the organization
* Reservation data: dates, status and guest counts
* Reservation accesses: smart lock PIN codes and lock information of reservations
* Smart locks: the smart locks of the organization and their PIN codes. You can create, change and delete manual codes.
* Operations: the status of a change that Guestway makes in the background, for example a new smart lock code
* Conversations and messages
* Organization users

The full reference is at [api.guestway.io/swagger/open](https://api.guestway.io/swagger/open). **Download** on that page gets the OpenAPI specification.

## Authentication

Every request needs two headers.

| Header                    | What it does                                                                                                                                                       | Security                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| **X-Api-Key**             | The Partnership API Key. It identifies your integration as a Guestway partner and applies the rate limits. Without a valid key, every request is rejected at once. | Gives no access to data on its own.                                      |
| **Authorization: Bearer** | The organization access token. It identifies your organization and applies the permissions of the token.                                                           | Gives access to the data of your organization. Treat it like a password. |

* You get the Partnership API Key from Guestway, with a partnership agreement. Contact <support@guestway.io>.
* Guestway gives one Partnership API Key to each customer, holding or entity. You use this one key for all your integrations and automations.
* The Partnership API Key works for all your organizations, also for organizations that you add later.
* You cannot get a second Partnership API Key for a new automation. A new automation gets its own organization access token instead. See [About partnership API keys and access tokens](https://docs.guestway.io/account-and-administration/api-access/about-partnership-api-keys-and-access-tokens.md).
* Default rate limits: 5 requests per second, with bursts up to 10 per second, and 10,000 requests per day. All your integrations and automations share the rate limits of your Partnership API Key. Contact support for higher limits.
* Organization access tokens are opaque tokens, not JWTs. They start with **gw\_**.
* Every organization can open this page and create tokens. The tokens work only together with a Partnership API Key.

```
X-Api-Key: <your partnership api key>
Authorization: Bearer gw_<your organization access token>
```

## API Access tab

The organization access tokens, as cards or as a table. **Create** makes a new token. An organization can have several active tokens.

| Column          | What it shows                                                                                            |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| **Name**        | The name of the token.                                                                                   |
| **API Token**   | The last characters of the token. The full token shows only once, when you create it.                    |
| **Permissions** | The permissions of the token.                                                                            |
| **Created**     | When the token was created.                                                                              |
| **Last Used**   | When the token was last used to call the API. Cards show *Not used yet* for a token that was never used. |

Click a token to open its details:

* **Information**: the **Name** (at most 255 characters), the **API token** ending, **Created**, **Last used** and **Permissions**. The pencil changes the name and the permissions.
* **Manage**: **Delete API access token** deletes the token. A deleted token cannot be restored.

Tokens have no expiry date, and there is no button to regenerate a token.

### Token permissions

Each token needs at least one permission. **Select all** selects every permission. The permissions, in the order of the product:

| Permission                                   | Permission                          |
| -------------------------------------------- | ----------------------------------- |
| **Full Access - Read**                       | **Full Access - Edit**              |
| **Reservation Accesses - Read**              | **Reservation Accesses - Edit**     |
| **Organization Users - Read**                | **Conversations - Read**            |
| **Conversations - Edit**                     | **Reservations - Read**             |
| **OTA Reservations - Read**                  | **OTA Listings - Read**             |
| **Reservations - Edit**                      | **Custom Field - Read**             |
| **Custom Field - Edit**                      | **Pre-Check-In Responses - Read**   |
| **Guests - Read**                            | **Listings - Read**                 |
| **Listings - Edit**                          | **Multi-Units - Read**              |
| **Complexes - Read**                         | **Bookings - Read**                 |
| **Owners - Read**                            | **Messages - Send**                 |
| **WhatsApp Templates - Read**                | **Webhooks - Read**                 |
| **Webhooks - Edit**                          | **Q\&A Records - Read**             |
| **Q\&A Records - Edit**                      | **Guidebooks - Read**               |
| **Guidebooks - Edit**                        | **Reservation Documents - Read**    |
| **Reservation Documents - Edit**             | **Internal Notes - Edit**           |
| **Holding Managed Accounts - Read**          | **Holding Managed Accounts - Edit** |
| **Holding Managed Accounts - Access Tokens** | **Roles - Read**                    |
| **Roles - Edit**                             | **Smart Locks - Read**              |
| **Smart Lock Codes - Read**                  | **Smart Lock Codes - Edit**         |
| **Operations - Read**                        |                                     |

* **Full Access - Read** and **Full Access - Edit** give read or read-and-write access to the whole platform.
* **Messages - Send** sends messages on behalf of your organization.
* **Conversations** permissions read or change the conversations of the [Unified AI inbox](https://docs.guestway.io/inbox-and-messaging/unified-ai-inbox.md). **Custom Field** permissions work with [Custom fields](https://docs.guestway.io/properties/custom-fields.md).
* **Smart Lock Codes - Edit** creates, changes and deletes manual smart lock codes. Guestway makes the change in the background. **Operations - Read** shows when the change is finished.

## Webhooks tab

Webhooks send events from Guestway to your own system. An organization can have at most 5 webhooks.

| Field                   | What it does                            | Limits                                                                                          |
| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Name**                | The name of the webhook.                | Optional, at most 255 characters.                                                               |
| **URL**                 | The endpoint that receives the events.  | Required. A public HTTPS address, at most 2,048 characters. Guestway does not follow redirects. |
| **Event types**         | The events that the webhook sends.      | At least one.                                                                                   |
| **Notification emails** | Who gets an email when deliveries fail. | At least one, at most 3.                                                                        |
| **Description**         | Your own notes.                         | Optional, at most 255 characters.                                                               |

If your endpoint answers a delivery with a redirect (an HTTP 3xx response), Guestway does not follow it, and the delivery fails.

Event types:

* **Reservation updated**, **Reservation custom fields updated**
* **Conversation updated**, **New conversation message**
* **Listing updated**, **Listing custom fields updated**
* **Complex updated**, **Complex custom fields updated**
* **Multi-unit updated**, **Multi-unit custom fields updated**
* **Custom field definition updated**, **Custom field definition deleted**
* **Q\&A record updated**
* **Smart lock updated**
* **Smart lock code updated**, **Smart lock code deleted**
* **Smart lock code operation finished**

**Smart lock code operation finished** is sent only for changes that were made through the Open API, when the change is finished.

Webhook statuses:

| Status       | Meaning                                                                                              |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| **Active**   | The webhook sends events.                                                                            |
| **Paused**   | You paused the webhook. It sends no events.                                                          |
| **Disabled** | Guestway turned the webhook off. It sends no events, and the events of that time are not sent later. |

Guestway disables a webhook automatically in two cases:

* The endpoint answers a delivery with HTTP 410 Gone. No email is sent.
* An hourly check finds that in the last 3 days there were at least 150 delivery attempts, and at least 95% of the deliveries failed for good, after all 5 attempts. Guestway then emails the **Notification emails** of the webhook.

**Re-enable webhook** turns it on again.

### Authentication of deliveries

Guestway signs every delivery with HTTP Basic Auth. The credentials show after you create a webhook, and in its details under **Authentication credentials**:

* **Name**: the ID of your organization, used as the user name
* **Secret**: the password
* **Header**: the full Authorization header

You can show the secret again at any time.

### Webhook details

Click a webhook to open its details. The pencil on **Information** changes the fields. **Manage** has these actions:

| Action                                 | What it does                                              |
| -------------------------------------- | --------------------------------------------------------- |
| **Pause webhook** / **Resume webhook** | Stops or restarts the deliveries.                         |
| **Re-enable webhook**                  | Turns on a **Disabled** webhook.                          |
| **Regenerate secret**                  | Makes a new secret. The old secret stops working at once. |
| **Delete webhook**                     | Deletes the webhook.                                      |

There is no button to send a test event or to send a delivery again.

## Webhook Logs tab

Every delivery of every webhook. You can filter by **Status**, **Event type**, **Resource ID** and **Received at**.

| Column             | What it shows                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| **Received**       | When Guestway received the event.                                                                        |
| **Event**          | The event type.                                                                                          |
| **Status**         | **Delivered**, **Failed** (Guestway can still try again) or **Final failure** (Guestway stopped trying). |
| **Response**       | The HTTP status code your endpoint returned.                                                             |
| **Resource ID**    | The ID of the reservation, listing or other item of the event.                                           |
| **Failure reason** | Why the delivery failed.                                                                                 |
| **Completed**      | When the delivery ended.                                                                                 |

## Related

* [How to create an API access token](https://docs.guestway.io/account-and-administration/api-access/how-to-create-an-api-access-token.md)
* [How to rotate or revoke an API token](https://docs.guestway.io/account-and-administration/api-access/how-to-rotate-or-revoke-an-api-token.md)
* [How to add a webhook](https://docs.guestway.io/account-and-administration/api-access/how-to-add-a-webhook.md)
* [About partnership API keys and access tokens](https://docs.guestway.io/account-and-administration/api-access/about-partnership-api-keys-and-access-tokens.md)
* [Guestway Open API reference](https://api.guestway.io/swagger/open)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.guestway.io/account-and-administration/api-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
