Identity & AccessAuth: API Key Only (Login/Register) or Bearer JWT (/auth/me)

Guest Authentication API

Handles guest registration, password-based login, profile hydration (/auth/me), and Google OAuth integration. All endpoints are tenant-scoped via the hotel API key.

POSThttps://api.thegrandeur.vip/api/v1/auth/login

Header Parameters

X-API-Keystringrequired

Your hotel live public API key (e.g. hak_live_...). Binds the guest to your specific hotel tenant.

Example: hak_live_8f3a1290...

Authorizationstring

Bearer JWT access token required for /auth/me and protected guest routes.

Example: Bearer eyJhbGciOiJIUzI1NiIsIn...

Request Body Schema (JSON)

emailstringrequired

The guest's email address.

Example: [email protected]

passwordstringrequired

The guest's account password.

Example: ••••••••

audiencestringrequired

Must be explicitly set to 'guest_site' for front-of-house guest web portals.

Example: guest_site

api_keystringoptional

Hotel API key echoed in the request body for legacy CORS compatibility.

Example: hak_live_8f3a1290...

Google OAuth 2.0 Flow

To initiate Google Sign-in on a custom frontend, redirect the guest browser to:

https://api.thegrandeur.vip/api/v1/social/google/login?api_key=hak_live_...&return_origin=https://your-site.com

After authentication, Google redirects back to your domain at /auth/callback?token=.... Your client can then save this token and call GET /auth/me to populate the user state.

# 1) Login with Hotel API Key
curl -s -X POST "https://api.thegrandeur.vip/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hak_live_YOUR_KEY" \
  -d '{
    "email": "[email protected]",
    "password": "••••••••",
    "audience": "guest_site",
    "api_key": "hak_live_YOUR_KEY"
  }'

# 2) Register New Guest
curl -s -X POST "https://api.thegrandeur.vip/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hak_live_YOUR_KEY" \
  -d '{
    "first_name": "Eleanor",
    "last_name": "Vance",
    "email": "[email protected]",
    "password": "••••••••"
  }'

# 3) Hydrate Session (/auth/me)
curl -s "https://api.thegrandeur.vip/api/v1/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: hak_live_YOUR_KEY"

Response Preview

{
  "success_status": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "usr_9a4f21b",
      "email": "[email protected]",
      "first_name": "Eleanor",
      "last_name": "Vance",
      "role": "guest"
    },
    "tokens": {
      "access": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
        "expires": "2026-10-01T12:00:00.000Z"
      },
      "refresh": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
        "expires": "2026-11-01T12:00:00.000Z"
      }
    }
  }
}

Webhooks & Sync

Rooms & Availability