API Key: Permissions, Validity, Rotating

When creating an API key under Integrations → API / MCP, tab API keys, "New Key", you define what it is allowed to do and how long it is valid. How to create and use the key: see Data API: Keys, Access, and Documentation.

Permissions: what the key is allowed to do

At the beginning, everything is set to Off. Only release what the program really needs. Without any permission, no key can be created. The permissions are divided into three blocks:

• Without customer data, each Off, Read, or Read and write: Bookings and calendar (with insurance), Units and prices (with availability), Guest guides, and Set up webhooks (a program like Zapier or Make creates webhooks itself). Bookings arrive here without guest data: only date, unit, price, and number of people. "Read all" and "Read and write all" set this block all at once.
• With customer data, to be checked individually: "Guest data in bookings" (name, email, phone, address, and ID data of the guests; only works together with Bookings and calendar), "Guest messages" (the conversations with your guests, also door codes written in them; Read or Read and write), and "Read invoices".
• Access: Door code, door links, check-in link, Wi-Fi password, and the custom fields of the unit.

If you check something from "With customer data" or "Access", you confirm: "This key releases customer data or access to your apartments. I am responsible for keeping it safe, not Xentra."

What happens without a permission

Every endpoint checks its permission, even when reading. Without "Guest data in bookings", the name, contact, and ID fields of a booking come back empty (null), and setting a guest's email or phone is answered by the API with 403. Without Access, the door code, check-in link, guest guide link, Wi-Fi password, and custom fields of the unit are empty, and the link endpoints answer with 403. Invoices need "Read invoices", guest messages need "Guest messages". The error message states the missing permission, for example write:bookings or read:invoices.

The permissions of a key cannot be changed afterwards; create a new one for that. Only entire areas can be released, no individual endpoints. Keys that you created before permissions were introduced keep everything they could do so far and continue to run without an expiration date.

Validity

When creating, you choose 90 days, 1 year (recommended), or Never expires. Unlimited is not recommended: a stolen or forgotten key would remain valid permanently. 30 and 7 days before expiration, we remind you via bell and email, plus once when it has expired.

In the list, the Permissions column shows abbreviations like "Bookings: read", "Guest data", or "Access". The Status column shows Active with "until " or "never expires" (orange starting 30 days before the end), Expired, Replaced, or Revoked.

Rotating and renewing

• Rotate (arrow symbol, "Rotate: new key, same permissions"): After "Create new key", you get a new key with the same permissions and the same validity period, the name is incremented (from "Zapier" to "Zapier_2"). Enter it in your program: the old one still works for 24 hours, after which it is set to Replaced. Each key can be rotated once.
• Renew appears for an expired or revoked key and creates a new one with the same permissions. A revoked key remains locked forever.

Rotating and renewing, like creating, require an active subscription. Connections with Claude or ChatGPT (the name ends with "(MCP)") cannot be rotated or renewed here: to change them, you remove them and reconnect the assistant, see Connecting Claude or ChatGPT with Xentra (MCP).