Authentication

Every request to the PMS API must include a valid API key as a Bearer token in the Authorization header.

API Key Format

Keys follow a prefixed format inspired by Stripe — the prefix tells you the key type at a glance:

pms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
└──────┘ └──────────────────────────────────┘
 prefix          32-character random hex

Key Type	Prefix	Purpose
Live	`pms_live_`	Production — creates real guest records, triggers dashboard updates
Test	`pms_test_`	Sandbox — validates your payloads but writes NO data. Learn more →

How to Authenticate

Include your API key as a Bearer token in the Authorization header of every request:

curl -X POST https://app.recepai.ai/api/pms/v1/grand-hotel/guests/checkin \
  -H "Authorization: Bearer pms_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkin_RES001_20260218" \
  -d '{"pmsGuestId": "RES-001", "lastName": "Doe", "roomNumber": "301", "checkOutDate": "2026-02-22"}'

All POST endpoints also require an Idempotency-Key header. See Testing & Rate Limits for details.

How to Get an API Key

API keys are generated by the hotel administrator (not by RecepAI or the PMS provider):

Hotel admin opens Settings → PMS Integration

In the RecepAI admin panel, the hotel staff navigates to their PMS Integration settings page.

Hotel admin clicks 'Generate API Key'

The system generates a live key (pms_live_) and a test key (pms_test_) together as a pair. Both full keys are displayed once — after that, only masked previews are visible.

Hotel admin shares the key with you

The hotel sends the API key and their hotel slug to your technical team through a secure channel. Recommended options:

One-time secret link: onetimesecret.com — the link self-destructs after one view
Password manager sharing (1Password, Bitwarden, etc.)
Encrypted email (PGP, S/MIME)

Security: Handle keys carefully.The API key grants full read/write access to the hotel’s guest data.Never share via: Plain email, WhatsApp, SMS, Slack DM, or any unencrypted messaging app. These leave the key in chat history permanently.Never expose in: Client-side code, public repositories, or log files.If a key is compromised, the hotel admin can revoke it immediately and generate a new one.

Key Lifecycle

Action	Who does it	What happens
Generate	Hotel admin	A live key and test key are created together as a pair. Previous revoked keys are not affected.
Use	Your PMS	Every API call authenticates with the live or test key. Usage is tracked (last used, request count).
Revoke	Hotel admin	Both keys (live and test) are immediately invalidated. All subsequent requests return `401 KEY_REVOKED`.
Regenerate	Hotel admin	Both old keys are revoked and a new pair is generated in a single operation.

Authentication Errors

If authentication fails, you’ll receive one of these responses: Missing or malformed header (401):

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Missing or malformed Authorization header. Use: Bearer pms_live_xxx",
  "requestId": "req_a1b2c3d4"
}

Invalid or wrong API key (401):

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid credentials",
  "requestId": "req_a1b2c3d4"
}

Revoked API key (401):

{
  "status": "error",
  "code": "KEY_REVOKED",
  "message": "API key has been revoked. Contact hotel admin for a new key.",
  "requestId": "req_a1b2c3d4"
}

The KEY_REVOKED error is the only authentication error with a specific code. All other failures return a generic UNAUTHORIZED to prevent key enumeration attacks.

Getting Started

Endpoints

Reference

API Key Format

How to Authenticate

How to Get an API Key

Key Lifecycle

Authentication Errors

​API Key Format

​How to Authenticate

​How to Get an API Key

​Key Lifecycle

​Authentication Errors

API Key Format

How to Authenticate

How to Get an API Key

Key Lifecycle

Authentication Errors