Skip to main content
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 TypePrefixPurpose
Livepms_live_Production — creates real guest records, triggers dashboard updates
Testpms_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):
1

Hotel admin opens Settings → PMS Integration

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

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.
3

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

ActionWho does itWhat happens
GenerateHotel adminA live key and test key are created together as a pair. Previous revoked keys are not affected.
UseYour PMSEvery API call authenticates with the live or test key. Usage is tracked (last used, request count).
RevokeHotel adminBoth keys (live and test) are immediately invalidated. All subsequent requests return 401 KEY_REVOKED.
RegenerateHotel adminBoth 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.