> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recepai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API key format, Bearer token authentication, and key management.

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 →](/api/pms/testing) |

## How to Authenticate

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

```bash theme={null}
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"}'
```

<Note>
  All POST endpoints also require an `Idempotency-Key` header. See [Testing & Rate Limits](/api/pms/testing) for details.
</Note>

## How to Get an API Key

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

<Steps>
  <Step title="Hotel admin opens Settings → PMS Integration">
    In the RecepAI admin panel, the hotel staff navigates to their PMS Integration settings page.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](https://onetimesecret.com) — the link self-destructs after one view
    * **Password manager sharing** (1Password, Bitwarden, etc.)
    * **Encrypted email** (PGP, S/MIME)
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

## 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):**

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

**Invalid or wrong API key (401):**

```json theme={null}
{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid credentials",
  "requestId": "req_a1b2c3d4"
}
```

**Revoked API key (401):**

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

<Tip>
  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.
</Tip>