> 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/settings/organization-settings/api-access.md). # API Access Use this page to manage Organization Access Tokens — the credentials your systems use to call the Guestway Open API for automation, integrations, and data sync. {% hint style="warning" %} Treat tokens like passwords. Anyone with a valid token can access your organisation's data via the API. {% endhint %} ### The Guestway Open API The Guestway Open API is built for business partners to integrate with the Guestway platform programmatically, and is designed for server-to-server communication. The current surface is intentionally limited, with scope to grow based on partner needs. Currently available: * Organization data — basic organisation information. * Reservation data — booking information including dates, status, and guest counts. * Reservation accesses — smart lock PIN codes and lock information tied to reservations. * Conversations and messages — guest communication data. * Organization users — team member information. Full reference: [api.guestway.io/swagger/open](https://api.guestway.io/swagger/open). Click Download on the reference page to grab the OpenAPI specification. ### Authentication: two headers required Every request to the Guestway Open API requires two headers, working together. They serve different purposes: | Header | Purpose | Security-sensitive? | | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | X-Api-Key | Partnership API Key — identifies your integration as a Guestway partner and applies rate limits. | No — does not grant access to any data on its own. | | Authorization: Bearer \ | Organization Access Token — authenticates your organisation and enforces the token's configured permissions. | Yes — grants access to your organisation's data. | #### 1. Partnership API Key * Header: X-Api-Key * Purpose: identifies your integration as a Guestway partner and enforces rate limits. * Security: not security-sensitive — it does not grant access to any data or resources on its own. * Required: without a valid Partnership API Key, requests are rejected immediately. * How to get one: contact to request your Partnership API Key. **Default rate limits** * 5 requests per second (with bursts tolerated up to 10 per second). * 10,000 requests per day. Contact if you need higher limits for your use case. **Example header** ``` X-Api-Key: abcd1234efgh5678 ``` #### 2. Organization Access Token * Header: Authorization: Bearer \ * Purpose: authenticates your organisation and enforces the permissions configured on the token. * Security: is security-sensitive — it grants access to your organisation's data. * Token type: opaque tokens (not JWTs), prefixed with gw\_. * Management: create, rotate, and revoke tokens from this page — Settings → API Access. You can keep multiple tokens active per organisation. **Example header** ``` Authorization: Bearer gw_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz ``` ### Availability The API Access page is available to every organisation — you can browse it and create Organization Access Tokens regardless of whether you have a partnership with Guestway. The tokens only become useful once you also have a Partnership API Key, which is gated behind a partnership agreement. Without a valid X-Api-Key, every request is rejected immediately, so an Organization Access Token on its own won't get you anywhere. To start using the Guestway Open API, contact to set up a partnership agreement and receive your Partnership API Key. ### What you can do here From Settings → API Access, you can: * View existing tokens and their status. * Create new tokens for integrations or internal tools. * Revoke tokens you no longer trust or need. The token list shows one row per token, with these columns: | Column | What it tells you | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | Name | The label you gave the token when you created it. | | API Token | The last characters of the token (masked as \*\*\*\*\*\*\*\*\*xyz). The full value is only shown once, at creation. | | Permissions | The scopes attached to the token. | | Created | When the token was created. | | Last Used | When the token was last used to call the API. Empty if it's never been used. | ### Create a token {% stepper %} {% step %} ### Create Click Create token. Give it a clear name. Use the system name and environment. Examples: * Zapier - production * Data export - staging {% endstep %} {% step %} ### Choose permissions Select the scopes the token should carry. Each scope grants access to a specific slice of the API: * Full Access - Read / Full Access - Edit — broad read or read/write access across the platform. Use sparingly. * Reservations - Read and Bookings - Read — reservation and booking data. * Reservation Accesses - Read — access-code data tied to reservations. * Conversations - Read / Conversations - Edit — read or modify guest conversations from the [Unified AI Inbox](https://docs.guestway.io/guestway-platform/unified-ai-inbox). * Messages - Send — send outbound messages on behalf of your organisation. * Guests - Read, Owners - Read, Organization Users - Read — read guest, owner, and user records. * Listings - Read, Multi-Units - Read, Complexes - Read — read property data at each level. * Custom Field - Read / Custom Field - Edit — work with [Custom Fields](https://docs.guestway.io/settings/organization-settings/custom-fields). * Pre-Check-In Responses - Read — read responses from the pre-arrival guest journey. * WhatsApp Templates - Read — list approved WhatsApp templates. Grant the minimum set of scopes the integration actually needs — it's the cleanest way to limit blast radius if a token is ever leaked. {% endstep %} {% step %} ### Copy and store Copy the token right away — it starts with gw\_ and the full value is only displayed once. Store it in a secret manager. Do not paste it into docs or tickets. {% endstep %} {% step %} ### Use it in your integration Add both headers to every API request: ``` X-Api-Key: Authorization: Bearer gw_ ``` See the [Guestway Open API reference](https://api.guestway.io/swagger/open) for endpoint and payload details. {% endstep %} {% endstepper %} ### Rotate or revoke tokens Rotate tokens on a schedule, or after any suspected exposure. To rotate safely: 1. Create a new token. 2. Update your integration to use the new token. 3. Confirm requests succeed. 4. Revoke the old token. To revoke a token, click the trash icon on its row and confirm — a popover asks *"Are you sure you want to remove this access token?"* before the token is permanently deleted. Revoked tokens are gone for good and can't be restored. The Last Used column is your best friend here: any token that hasn't been used in months is a candidate for retirement. ### Troubleshooting * 401 / Unauthorized — token is missing, revoked, or incorrect. Check that Authorization: Bearer gw\_... is set on the request. * 403 / Forbidden — your token lacks the scope required for the resource you're trying to reach. Check the Permissions column on the token's row. * Rate limit errors — you're exceeding 5 requests per second or 10,000 per day. Throttle the client or contact for higher limits. * Requests rejected immediately — the X-Api-Key header is missing or invalid. Confirm the Partnership API Key is set on every request. * Nothing works — confirm you have a valid Partnership API Key from Guestway and that it's set on the X-Api-Key header of every request. Without it, the request is rejected before your Organization Access Token is even checked. ### Related pages * [Guestway Open API reference](https://api.guestway.io/swagger/open) — endpoints, parameters, and response shapes for the Open API. * [Custom Fields](https://docs.guestway.io/settings/organization-settings/custom-fields) — the custom data that the Custom Field scopes give access to. * [Unified AI Inbox](https://docs.guestway.io/guestway-platform/unified-ai-inbox) — the conversations a token with Conversations scopes can read or modify. * [Users](https://docs.guestway.io/settings/organization-settings/users) — manage who in your organisation can create and revoke API tokens. --- # 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://docs.guestway.io/settings/organization-settings/api-access.md?ask=&goal= ``` `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.