Skip to content

Club externo

Loyalty sign-in for booking engines

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.

Use this page if
  • 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.
Use the OIDC quickstart instead if
  • You have one fixed callback URL, or you already use an OpenID Connect library.
Go to the OIDC quickstart

How it works

Three parties: the guest’s browser, your booking engine and GuestMaker. The guest never leaves for more than one login page.

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

  2. 2GuestGuestMaker

    The guest signs in to the hotel’s club. Already signed in within the last 30 days? They skip the form.

  3. 3GuestMakerYour engine

    The browser lands back on your page, unchanged, with a one-time code added to the URL.

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

ItemWhat it is
client_idIdentifies your booking engine. Public: it goes in the login URL.
client_secretShown to you once. Keep it on your server: it must never reach a browser.
Allowed return hostsThe 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 modeHow 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

ParameterRequiredMeaning
client_idYesYour client id.
redirectUrlYesWhere 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.
localeNoLanguage of the login page: pt, es, en, fr, de or it. Also accepted as lang.
promptNonone 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 seeWhenWho can read it
?hlCode=…Delivery mode codeYour server. A one-time code, valid for 5 minutes.
#hlToken=…Delivery mode fragmentOnly the browser: the part after # is never sent to a server.
Both of the aboveDelivery mode bothUse the code and ignore the token.
?hlError=login_requiredOnly with prompt=noneThe 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

FieldNotes
id, email, firstName, lastName, tierAlways present.
phone, address, city, zipCode, country, languagenull when the hotel does not hold the value.
marketingConsenttrue, 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

WhereAnswerMeaning and what to do
Login pageAn 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, me401 invalid_clientWrong client id or secret.
exchange400 invalid_requestNo code in the request body.
exchange400 invalid_grantThe 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.
me401 invalid_tokenThe token has expired (after 5 minutes) or was revoked by a logout. Send the guest to the login again.
exchange, me429Too many requests. Wait and try again.
If the guest signs in and never arrives
This failure shows no error on either side.

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-action Content-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.
A working engine you can run
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.

Cookie policy