# 2. Microsite authentication
## About authentication in the Loyalty Microsite
User authentication enables users to sign up, log in, and access the Loyalty Microsite and their rewards. There are two main options:
1. [**Embedded authentication**](#embedded-authentication)\
This option allows users to sign up and log in using your existing app or website flow. Users are automatically logged in to the microsite using the same credentials they already use on your platform, creating a seamless and transparent experience.
2. [**Interactive authentication**](#interactive-authentication)\
In this option, users create a dedicated account for the Loyalty Microsite, using a separate sign-up and login flow specifically for the loyalty program.
***
## Embedded authentication
To embed the Loyalty Microsite and ensure users are authenticated transparently, **session tokens** are used. These tokens allow users to access the microsite without needing to log in separately. When embedding the Loyalty Microsite, there are two options for passing the session token:
* **Session Token in URL:** The session token is appended directly to the URL query parameter, which loads the microsite in a logged-in state.
* **Session Cookie:** The session token is stored as a cookie in the user’s browser, shared across both the microsite and the main website for automatic login.
### Creating the user’s session token
To initiate a user’s session in the microsite without requiring manual login, you’ll need to send an HTTP request from a secure server-side context with the user’s details to `https://MICROSITEURL.COM/api/auth`.
This request accomplishes two things:
1. **Authenticates the User:** It specifies the user to authenticate (via the `selector.authIdentifier` property).
2. **Updates Profile Information:** If the user already has an account, their profile details are updated with the data in the request. If no account exists, the microsite will create one in the Loyalty Engine just in time based on the provided data.
#### Required Parameters
Include the following fields in the request:
* **X-Client-ID header**: Identifies the requester.
* **selector.authIdentifier:** Matches the pre-existing user identifier used in your website or app session.
* **profile Fields**: `emailAddress`, `givenName`, and `familyName` (mandatory); [other fields](/product/loyalty-engine/users/user-data-attributes-and-flags.md) are optional but recommended for a more tailored user experience.
{% hint style="info" %}
This method is an **upsert** process, meaning it creates a new user if none exists, or updates the profile if the user already exists.
{% endhint %}
Request Example
{% code overflow="wrap" lineNumbers="true" %}
```http
POST /api/auth HTTP/1.1
Host: https://MICROSITEURL.COM
Content-Type: application/json
Accept: application/json
X-Client-ID: CLIENT-ID-HERE
{
"selector": {
"authIdentifier": "USER-IDENTIFIER-HERE"
},
"profile": {
"givenName": "Jane",
"familyName": "Doe",
"emailAddress": "jane.doe@example.com",
"gender": "FEMALE",
"birthdate": "1980-01-01",
"country": "GB",
"city": "Leeds",
"postcode": "LS1 5PZ",
"pictureUrl": "https://example.com/pic.jpg",
"streetAddress": "99 Road Street",
"region": "West Yorkshire",
"telephoneNumber": "01437532699"
}
}
```
{% endcode %}
Response Example
{% code overflow="wrap" lineNumbers="true" %}
```http
HTTP/1.1 200 OK
Set-Cookie: session=p%2B6BqjiOhRvKvD0DxX632%2FAEiZExMAAY4AEQR1qt%2Bhr1nRLdoxuTrS01kecZjPsyMwGQ6GoyiaQvxW%2BNLXWnrYdeWoIoemeg0RU2qkEn4A%3D%3D; Max-Age=259200; Domain=customer.web.wlloyalty.net; Secure; SameSite=None
Content-Type: application/json; charset=utf-8
Content-Length: 384
{
"status": "success",
"data": {
"user": {
"externalIdentifier": "5b2257d404e0e30bf729cbf2"
"authIdentifier": "5b2257d404e0e30bf729cbf2",
"isRestricted": false,
"id": "d9d35027-58e3-4167-8e22-a81728f46f62",
"createdAt": "2018-07-20T09:19:54.699Z",
"updatedAt": "2019-08-21T10:22:48.017Z",
"flags": {
"genderProvided": true
}
},
"session": "p+6BqjiOhRvKvD0DxX632/AEiZExMAAY4AEQR1qt+hr1nRLdoxuTrS01kecZjPsyMwGQ6GoyiaQvxW+NLXWnrYdeWoIoemeg0RU2qkEn4A=="
}
}
```
{% endcode %}
{% hint style="warning" %}
**This HTTP request should be made from a secure server-side context.**
It **should not** be made from a client-side context since that would expose the X-Client-ID which could then enable a malicious actor to impersonate a user if they knew the user's ID.
{% endhint %}
### Activating the user's session
Upon a successful request, the response body will contain the session token within the `session` property. To use this token for automatic login in the microsite, you can either:
1. Append the Session Token to the **URL as a query parameter**
2. Set the Session Token directly as a **Cookie**
#### Selecting an approach
The **query parameter** method is ideal when opening the microsite in a new window or tab after authenticating the user on your own website. This approach is straightforward but requires an initial redirect to the microsite’s homepage, which may impact user experience slightly.
For embedding the microsite within an iframe on your website, we recommend using the **cookie method**. Setting the cookie as “HttpOnly” prevents the session token from being accessible to client-side code, reducing potential security risks. Additionally, the cookie method enables direct loading of any page within the microsite in an authenticated state, without requiring the initial redirect needed by the query parameter approach.
Passing Session via Query Parameter
To pass the session token directly in the URL, append it as a query parameter. For example:
```url
https://MICROSITEURL.COM/api/auth?session=abc123
```
This configuration automatically redirects users to the microsite homepage if the session token is valid. To redirect to a different page, add a `redirect_path` parameter:
```url
https://MICROSITEURL.COM/api/auth?session=abc123&redirect_path=/activity
```
Passing Session via Cookie
To configure session authentication using cookies, create a cookie with the following configuration and add it to the browser’s ambient environment.
The cookie domain should be set to the base domain shared between the microsite and the parent website, for example, example.com if the microsite is at microsite.example.com and the main site is at [www.example.com](http://www.example.com). This setup ensures that cookies are accessible across both sites.
**Name:** session\
**Domain:** rootdomain.com\
**Path:** /\
**HttpOnly:** true\
**Secure:** true\
**SameSite:** None
An additional cookie may be set to support older browsers, configured as follows.
**Name:** session\_legacy\
**Domain:** rootdomain.com\
**Path:** /\
**HttpOnly:** true\
**Secure:** true
***
## Interactive authentication
If the microsite is operating in [**standalone mode**](/product/interfaces/white-label-interfaces/loyalty-microsite/loyalty-microsite-setup/1.-deployment-type/1.c-standalone-website-or-pwa.md), you can configure the **OAuth2** settings (as shown in the screenshot below) to allow your end-users to log in through your own identity server.
Interactive authentication configuration for the Loyalty Microsite
***
## FAQs
#### Can users switch between embedded and interactive authentication?
No, each microsite instance must be configured to use either embedded or interactive authentication exclusively. Switching between the two requires a reconfiguration of the authentication setup.
#### How secure is embedded authentication?
Embedded authentication can be highly secure when implemented with server-side session token generation and HttpOnly cookies. Avoid exposing sensitive identifiers or tokens client-side to minimise potential security risks.
#### What happens if user details change on our platform?
If a user’s details are updated on your platform, you can send an updated session token request to the microsite with the new profile data, or use the Update user profile API endpoint. This process automatically updates the user’s profile in the Loyalty Engine.
#### What if a user is logged out of our main website but still has an active microsite session?
In embedded authentication setups, logging out from your main website doesn’t automatically log the user out of the microsite. We recommend manually invalidating the session token or refreshing the iFrame if synchronised logout is needed.
#### Is it possible to add custom profile fields to the session token?
Yes, custom profile fields can be included in the session token request using the profile object. These custom fields will be added to the [user’s attributes in the Loyalty Engine](/product/loyalty-engine/users/user-data-attributes-and-flags.md) if they’re not core fields.
#### What's the default login session length on a microsite using WLL Auth Service in interactive auth mode?
If using the WLL authentication service (Auth0), user's remain logged in for 24 hours by default, after which point they will need to login again. This can be extended to up-to 30 days on request by contacting WLL Support.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://kbase.whitelabel-loyalty.com/product/interfaces/white-label-interfaces/loyalty-microsite/loyalty-microsite-setup/2.-microsite-authentication.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.