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.
Treat tokens like passwords. Anyone with a valid token can access your organisation's data via the API.
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. 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:
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 <token>
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 [email protected] 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 [email protected] if you need higher limits for your use case.
Example header
2. Organization Access Token
Header: Authorization: Bearer <token>
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
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 [email protected] 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:
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
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.
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.
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.
Use it in your integration
Add both headers to every API request:
See the Guestway Open API reference for endpoint and payload details.
Rotate or revoke tokens
Rotate tokens on a schedule, or after any suspected exposure.
To rotate safely:
Create a new token.
Update your integration to use the new token.
Confirm requests succeed.
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 [email protected] 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 — endpoints, parameters, and response shapes for the Open API.
Custom Fields — the custom data that the Custom Field scopes give access to.
Unified AI Inbox — the conversations a token with Conversations scopes can read or modify.
Users — manage who in your organisation can create and revoke API tokens.