User Context in Marketplace Apps

HighLevel provides a secure mechanism for accessing authenticated user information through signed tokens. This guide explains how you can generate and use Shared Secret key to access user context in secured manner.

Setting Up Shared Secret

Generating a Shared Secret Key

First you'll need to generate a Shared Secret key for your application:

1. Navigate to your application's Advanced Settings
2. Go to the Auth section
3. Under Shared Secret, click the Generate button to create your Shared Secret key

Frontend Implementation Methods

There are two ways in which you can access this data in your frontend, depending on where your code runs:

1. Custom JavaScript Implementation

If you're using custom JavaScript injected into HighLevel pages, use the exposeSessionDetails method:

async function getUserData() {
  try {
    // APP_ID is your application's unique identifier
    const encryptedUserData = await window.exposeSessionDetails(APP_ID);

    // Send this encrypted data to your backend for decryption
    const response = await fetch("your-backend-endpoint", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ encryptedData: encryptedUserData }),
    });

    const userData = await response.json();
    return userData;
  } catch (error) {
    console.error("Failed to fetch session details:", error);
    throw error;
  }
}

2. Custom Pages Implementation

If you're trying to get user context in custom page, use the postMessage method to communicate with the parent window:

async function getUserData() {
  try {
    const encryptedUserData = await new Promise((resolve) => {
      // Request user data from parent window
      window.parent.postMessage({ message: "REQUEST_USER_DATA" }, "*");

      // Listen for the response
      const messageHandler = ({ data }) => {
        if (data.message === "REQUEST_USER_DATA_RESPONSE") {
          window.removeEventListener("message", messageHandler);
          resolve(data.payload);
        }
      };

      window.addEventListener("message", messageHandler);
    });

    // Send encrypted data to your backend for decryption
    const response = await fetch("your-backend-endpoint", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ encryptedData: encryptedUserData }),
    });

    const userData = await response.json();
    return userData;
  } catch (error) {
    console.error("Failed to fetch user data:", error);
    throw error;
  }
}

Backend Implementation

Regardless of which frontend method you use, the backend decryption process remains the same:

const CryptoJS = require("crypto-js");

function decryptUserData(encryptedUserData, sharedSecretKey) {
  try {
    const decrypted = CryptoJS.AES.decrypt(
      encryptedUserData,
      sharedSecretKey
    ).toString(CryptoJS.enc.Utf8);
    return JSON.parse(decrypted);
  } catch (error) {
    throw new Error("Failed to decrypt user data");
  }
}

// Example Express endpoint
app.post("/decrypt-user-data", (req, res) => {
  try {
    const { encryptedData } = req.body;
    const userData = decryptUserData(
      encryptedData,
      process.env.GHL_APP_SHARED_SECRET
    );
    res.json(userData);
  } catch (error) {
    res.status(400).json({ error: "Failed to decrypt user data" });
  }
});

Decrypted Data Structure

After decryption, the data will be returned as a JSON object containing user information. The structure varies based on whether the user is accessing from an Agency or Location context.

Agency Context

When accessing from an Agency context, the decrypted data will have the following structure:

{
  "userId": "MKQJ7wOVVmNOMvrnKKKK", // Unique identifier for the user
  "companyId": "GNb7aIv4rQFVb9iwNl5K", // Unique identifier for the company/agency
  "role": "admin", // User's role in the system
  "type": "agency", // Indicates this is an agency user
  "userName": "John Doe", // Full name of the user
  "email": "[email protected]", // User's email address
  "isAgencyOwner": true, // If the loggedIn user is agency owner
  "region": "us", // HighLevel region that served this session
  "versionId": "695505b431a9710730ee67d7",
  "appStatus": "live",
  "whitelabelDetails": {
      "domain": "example.com",
      "logoUrl": "example.com"
    }
}

Location Context

When accessing from a Location context, the decrypted data will include an additional activeLocation field:

{
  "userId": "MKQJ7wOVVmNOMvrnKKKK", // Unique identifier for the user
  "companyId": "GNb7aIv4rQFVb9iwNl5K", // Unique identifier for the company/agency
  "role": "admin", // User's role in the system
  "type": "agency", // Indicates this is an agency user
  "activeLocation": "yLKVZpNppIdYpah4RjNE", // Unique identifier for the active location
  "userName": "John Doe", // Full name of the user
  "email": "[email protected]", // User's email address
  "isAgencyOwner": false, // If the loggedIn user is agency owner
  "region": "us", // HighLevel region that served this session
  "versionId": "695505b431a9710730ee67d7",
  "appStatus": "live",
  "whitelabelDetails": {
      "domain": "example.com",
      "logoUrl": "example.com"
    }
}

Field Descriptions

Field	Type	Description
userId	string	Unique identifier for the user
companyId	string	Unique identifier for the company/agency
role	string	User's role in the system (e.g., 'admin', 'user')
type	string	Context type ('agency' or 'location')
activeLocation	string	(Location context only) Unique identifier for the active location
userName	string	Full name of the user
email	string	User's email address
isAgencyOwner	boolean	If the loggedIn user is agency owner
region	string	HighLevel region that served this session (us, au, ...)

About region

region tells you which HighLevel deployment served this session, so your app can route its own storage and processing to match. Values are lowercase region codes such as us and au. Treat the list as open — more regions are added over time.

It is not a statement about where the account's HighLevel data is stored. Use it to decide where your application handles the data for this session, not as a data-residency guarantee.

Reading region without decrypting

region is also delivered outside the encrypted blob, so you can pick a region before you send the session anywhere — including before the decryption call itself. See Getting the region up front.

Treat this payload as additive

New fields are added to the decrypted object over time, inside the same encrypted blob. Read the keys your app needs and ignore any you do not recognise. Do not validate the decrypted object against a strict schema that rejects unknown keys, or a future field will break your app.

Reference Implementation

For a complete example implementation, you can refer to our marketplace app template repository:

HighLevel Marketplace App Template

The relevant implementation can be found in the /decrypt-sso endpoint of the template.

Security Considerations

• Never expose your Shared Secret key in client-side code
• Always perform decryption on your backend
• Store your Shared Secret key securely using environment variables
• Use HTTPS for all communications between your frontend and backend
• Regularly rotate your Shared Secret keys for enhanced security

Getting the region up front

Because region lives inside the encrypted payload, reading it from there means you have already sent the session somewhere to be decrypted. If your backend runs in more than one region, that first call has to go somewhere before you know where it should go.

To avoid that, region is also provided alongside the encrypted blob, unencrypted, so you can route the very first request — including the decryption — correctly.

Custom Pages

The REQUEST_USER_DATA_RESPONSE message carries region next to payload:

window.addEventListener("message", ({ data }) => {
  if (data.message !== "REQUEST_USER_DATA_RESPONSE") return;

  const encryptedUserData = data.payload; // unchanged
  const region = data.region; // "us", "au", ...

  // Send the blob to the backend for this region
  fetch(backendFor(region), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ encryptedData: encryptedUserData }),
  });
});

payload is unchanged — region is a separate key beside it, so existing handlers keep working without modification.

Custom JavaScript

Use exposeSessionDetailsWithRegion, which resolves to both values:

const { data, region } = await window.exposeSessionDetailsWithRegion(APP_ID);

await fetch(backendFor(region), {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ encryptedData: data }),
});

exposeSessionDetails is unchanged and still resolves to the encrypted string on its own, so existing integrations need no updates.

Use the encrypted copy for anything that must be trusted

The region delivered beside the payload is not part of the encrypted, signed blob, so treat it as a routing hint. When a decision needs a value your app can verify, read region from the decrypted payload instead — that copy is sealed with your Shared Secret.