Club externo
Let guests sign in to the hotel’s loyalty club from inside your booking engine. You send the guest to a GuestMaker login page; they come back to the exact page they left, with their dates, hotel and occupancy intact; and your server receives who they are: name, email and membership tier.
- The page the guest returns to changes with every search (it carries dates, hotel or occupancy).
- You would rather make two HTTP calls than add an OpenID Connect library.
- You have one fixed callback URL, or you already use an OpenID Connect library.
How it works
Three parties: the guest’s browser, your booking engine and GuestMaker. The guest never leaves for more than one login page.
- 1Your engineGuestMaker
The guest clicks “Sign in”. You redirect their browser to the GuestMaker login, with your client id and the page to come back to.
- 2GuestGuestMaker
The guest signs in to the hotel’s club. Already signed in within the last 30 days? They skip the form.
- 3GuestMakerYour engine
The browser lands back on your page, unchanged, with a one-time code added to the URL.
- 4Your backendGuestMaker
Your server swaps the code for the member: name, email, tier and the rest of the profile.
What you get from us
Four things, set up once per booking engine. Ask your GuestMaker contact for them.
| Item | What it is |
|---|---|
client_id | Identifies your booking engine. Public: it goes in the login URL. |
client_secret | Shown to you once. Keep it on your server: it must never reach a browser. |
| Allowed return hosts | The hosts the guest may be sent back to, such as book.hotel.com. Hosts, not exact URLs: any path and query on them is accepted. http://localhost is allowed for development. |
| Delivery mode | How the result is attached to your return URL: code (recommended), fragment, or both while you switch from one to the other. Step 2 shows each. |
1. Send the guest to the login
Redirect the guest’s browser to the login page. Pass the full URL of the page they should come back to, encoded as a single value: build it with a URL library, as below, so its own ? and & do not split it into separate parameters.
const returnUrl = "https://book.hotel.com/rates?checkin=2026-10-01&adults=2";
const login = new URL("https://www.guestmaker.ai/loyalty/club/login");
login.searchParams.set("client_id", process.env.GM_CLIENT_ID);
login.searchParams.set("redirectUrl", returnUrl); // encoded for you
login.searchParams.set("locale", "pt");
redirect(login.toString());Parameters
| Parameter | Required | Meaning |
|---|---|---|
client_id | Yes | Your client id. |
redirectUrl | Yes | Where the guest comes back to. Its host must be on your allowed list. Any #fragment on it is dropped (the result is added back as in step 2). Also accepted as domain. |
locale | No | Language of the login page: pt, es, en, fr, de or it. Also accepted as lang. |
prompt | No | none to check silently whether the guest is signed in; login to always show the form. See Keeping the guest signed in. |
2. Read what they bring back
The guest lands back on your return URL with one extra value added. Which one depends on your delivery mode:
| You see | When | Who can read it |
|---|---|---|
?hlCode=… | Delivery mode code | Your server. A one-time code, valid for 5 minutes. |
#hlToken=… | Delivery mode fragment | Only the browser: the part after # is never sent to a server. |
| Both of the above | Delivery mode both | Use the code and ignore the token. |
?hlError=login_required | Only with prompt=none | The guest is not signed in. Show your normal page. |
Never move the token into a query string to reach your server more easily: query strings are written to every proxy and access log on the way. That is exactly why the one-time code exists.
3. Get the member
Both calls run on your server and send your client credentials. Follow the block for your delivery mode.
Delivery mode code: swap the code for the member
A code works once, for 5 minutes, and only for the client it was issued to. If the call fails, do not retry it: send the guest to the login again. If they are still signed in, they come straight back with a new code.
const code = new URL(req.url).searchParams.get("hlCode");
const res = await fetch("https://www.guestmaker.ai/api/loyalty/club/exchange", {
method: "POST",
headers: {
"X-Client-Id": process.env.GM_CLIENT_ID,
"X-Client-Secret": process.env.GM_CLIENT_SECRET,
"Content-Type": "application/json",
},
body: JSON.stringify({ code }),
});
const { token, member } = await res.json();
// {
// "token": "eyJ…", ← keep it for step 4 (valid 5 minutes)
// "token_type": "Bearer",
// "expires_in": 300,
// "member": { "id": "…", "email": "…", "firstName": "…", "tier": "gold", … }
// }Delivery mode fragment: hand the token to your server
Your server cannot see the token, so a few lines of JavaScript on the return page post it to your own backend, which then reads the profile with it (step 4).
// On your return page, in the browser:
const token = new URLSearchParams(location.hash.slice(1)).get("hlToken");
if (token) {
history.replaceState(null, "", location.pathname + location.search); // drop it from the URL
await fetch("/club/token", { // your own endpoint
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ token }),
});
}
// On your server, in /club/token: read the member with that token (step 4).4. Read the profile with the token
With delivery mode code you already have the member from step 3, so you only need this to read it again while the token is still valid (5 minutes). With delivery mode fragment this is how you get the member. It needs the token and your client credentials together, so a stolen token alone cannot read a guest’s data.
const member = await fetch("https://www.guestmaker.ai/api/loyalty/club/me", {
headers: {
"X-Client-Id": process.env.GM_CLIENT_ID,
"X-Client-Secret": process.env.GM_CLIENT_SECRET,
Authorization: `Bearer ${token}`,
},
}).then((r) => r.json());The member profile
| Field | Notes |
|---|---|
id, email, firstName, lastName, tier | Always present. |
phone, address, city, zipCode, country, language | null when the hotel does not hold the value. |
marketingConsent | true, false, or null when the guest was never asked. |
Keeping the guest signed in
A guest who signs in once stays signed in with GuestMaker for 30 days, whichever engine or page they started from (a club engine, an OIDC engine or the member portal), until they log out. So whenever you need to know who the guest is, send them to the login: if they are signed in they come straight back and never see the form.
// Check silently on page load: never shows a page.
login.searchParams.set("prompt", "none");
// → back with ?hlCode= / #hlToken= when signed in
// → back with ?hlError=login_required when not
// Always show the form (switch account, shared computer):
login.searchParams.set("prompt", "login");
// Sign the guest out of GuestMaker too, from your own logout:
const logout = new URL("https://www.guestmaker.ai/loyalty/club/logout");
logout.searchParams.set("client_id", process.env.GM_CLIENT_ID);
logout.searchParams.set("redirectUrl", "https://book.hotel.com/");
redirect(logout.toString());The logout, like the login, only returns to a host on your allowed list, and it signs the guest out of GuestMaker on every device. Without it, your own sign-out lasts only until the next time you send the guest to us.
Errors
| Where | Answer | Meaning and what to do |
|---|---|---|
| Login page | An error page (403) | Unknown client id, the hotel’s loyalty programme is not live, or the return host is not on your allowed list. The guest is never redirected. Check the parameters, then contact us. |
| exchange, me | 401 invalid_client | Wrong client id or secret. |
| exchange | 400 invalid_request | No code in the request body. |
| exchange | 400 invalid_grant | The code is unknown, expired, already used or issued to another client. All four look the same on purpose. Send the guest to the login again. |
| me | 401 invalid_token | The token has expired (after 5 minutes) or was revoked by a logout. Send the guest to the login again. |
| exchange, me | 429 | Too many requests. Wait and try again. |
The sign-in can succeed and the browser can still refuse the final redirect back to you. Check, in order:
- Your return host is on the allowed list. If it is not, the login shows an error page before the guest signs in: the easy case.
- The browser console at the moment you press sign in. A
form-actionContent-Security-Policy error there names the login URL, not your return URL, so it looks as if the sign-in failed when it worked. Tell us: this one is ours to fix. - The login page expires after 15 minutes. A guest who leaves the tab and comes back starts again.
examples/loyalty-club-rp/server.mjs: one file, no dependencies.A fake booking engine that does everything on this page: both parameter spellings, all three delivery modes, the token handed back from the browser, and the profile read. It runs on localhost, which is allowed for exactly this.
GM_CLIENT_ID=… GM_CLIENT_SECRET=… node server.mjs # → http://localhost:4321
On startup it tries a real login against your setup and tells you whether the guest can make it back, before you click anything. Ask us for it with your sandbox credentials.