> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Identify the App Instance in a Site Widget Built with the CLI

## Article: Identify the App Instance in a Site Widget Built with the CLI

## Article Link: https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/site-extensions/custom-element-site-widgets/identify-the-app-instance-in-a-site-widget-built-with-the-cli.md

## Article Content:

# Identify the App Instance in a Site Widget Built with the CLI

<blockquote classname="note">

**CLI Documentation Notice**

We've released a [new Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). Continue here if your project uses the Wix CLI for Apps. [Determine which CLI your project uses](https://dev.wix.com/docs/wix-cli/guides/development/determine-which-cli-your-project-uses.md). 

</blockquote>

For security reasons, [app instance ID](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances.md) (`instanceId`) isn't directly accessible in [site widgets](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/add-a-site-widget-extension-in-the-cli.md) or settings panels. Instead, you can securely extract it by sending a Wix access token to a backend API. The backend can decode the token, get the instance ID or instance data, and perform any necessary business logic.

This article explains how to:

* **Backend:** Expose a backend API to identify the app instance.
* **Frontend:** Pass a Wix access token from your custom element to your backend.

## Step 1 | Expose a backend API

To securely identify the app instance:

1. [Add a Backend API Extension in the Wix CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/api/add-api-extensions-with-the-cli.md).

1. In the `api.ts` file of your backend API extension, import the `auth` submodule from the Essentials API:

    ```javascript
    import { auth } from "@wix/essentials";
    ```

1. Depending on your [use case](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances.md#example-use-cases-1), you may only need `instanceId` or you may need more detailed app instance data.

   * **To extract `instanceId`:**

     In the `GET` endpoint, call [`getTokenInfo()`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md#gettokeninfo) to extract `instanceId` from the access token.

    ```javascript
    const tokenInfo = await auth.getTokenInfo();
    const instanceId = tokenInfo.instanceId;
    ```

   * **To fetch instance data:**

     Elevate API call permissions to an app identity. Then, call [`getAppInstance()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/app-instances/get-app-instance.md). Elevation is necessary because access tokens sent from site widgets are tied to a site visitor or member [identity](https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities.md), which don't have access to instance data.

    ```javascript
    import { appInstances } from "@wix/app-management";

    // Elevate permissions in your GET endpoint
    const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance);
    const instanceResponse = await elevatedGetAppInstance();
    ```

## Step 2 | Pass a Wix access token to your backend

To pass a Wix access token from your custom element to your backend:

1. [Add a Site Widget Extension in the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/site-extensions/custom-element-site-widgets/add-a-site-widget-extension-in-the-cli.md). If you already have a site widget, skip to the next step.

1. In the `element.tsx` file of your site widget extension, import the `httpClient` submodule from the [Essentials API](https://dev.wix.com/docs/sdk/core-modules/essentials/introduction.md).

    ```javascript
    import { httpClient } from '@wix/essentials';
    ```

1. Call [`fetchWithAuth()`](https://dev.wix.com/docs/sdk/core-modules/essentials/http-client.md#fetchwithauth) to send a request to your backend with a Wix access token.

    ```javascript
    const response = await httpClient.fetchWithAuth(`${import.meta.env.BASE_API_URL}/<YOUR_BACKEND_API_NAME>`);
    ```

<blockquote class="tip">

**Tip:** To get `instanceId` in the settings panel, call `fetchWithAuth()` from your `panel.tsx` file.

</blockquote>

## Examples

Depending on your [use case](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances.md#example-use-cases-1), the logic of your backend API will vary. For example, you may only need to extract `instanceId` and then use it to make a request to your own database. Alternatively, you may wish to request app instance data from Wix, in which case you'd need to elevate your access token.

See the relevant example for your use case:

* [Backend: Extract `instanceId`](#backend-extract-instanceid)
* [Backend: Fetch instance data](#backend-fetch-instance-data)
* [Frontend: Call your backend](#frontend-call-your-backend)

### Backend: Extract `instanceId`

The following example is based on a CLI backend API extension called `get-instance`. The API extracts `instanceId` from the access token provided by the frontend request.

```javascript
import { auth } from "@wix/essentials";

// Edit this code based on your business logic
const mockDatabaseQuery = async (instanceId) => {
  console.log(`Mock database query with instance ID: ${instanceId}`);
  if (instanceId) {
      return {
          status: "Success",
      };
  } else {
      return {
          status: "No instance ID.",
      };
  }
};

export async function GET(req) {
  try {
    // Extract the app instance ID from the access token
    const tokenInfo = await auth.getTokenInfo();
    const instanceId = tokenInfo.instanceId;
    console.log("Instance ID:", instanceId);

    // Edit this code based on your business logic
    const data = await mockDatabaseQuery(instanceId);

    return Response.json(data)
  } catch (error) {
    console.error("Error decoding token:", error);
    return new Response(JSON.stringify({ error: "Failed to process request" }), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }
}
```

### Backend: Fetch instance data

The following example is based on a CLI backend API extension called `get-instance`. The API elevates permissions and requests instance data from Wix.

```javascript
import { auth } from "@wix/essentials";
import { appInstances } from "@wix/app-management";

export async function GET(req) {
  try {
    const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance);
    const instanceResponse = await elevatedGetAppInstance();

    return Response.json(instanceResponse.data)
  } catch (error) {
    console.error("Error decoding token:", error);
    return new Response(JSON.stringify({ error: "Failed to process request" }), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }
}
```

### Frontend: Call your backend

The following example creates a custom element that makes a request to the `get-instance` endpoint.

```javascript
import React, { useState, useEffect } from 'react';
import reactToWebComponent from 'react-to-webcomponent';
import ReactDOM from 'react-dom';
import styles from './element.module.css';
import { httpClient } from '@wix/essentials';

interface Props {
  displayName: string;
}

const CustomElement: React.FC<Props> = ({ displayName }) => {
  const [instanceData, setInstanceData] = useState<any>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const callMyBackend = async () => {
      try {
        // Send the access token to your backend
        const response = await httpClient.fetchWithAuth(`${import.meta.env.BASE_API_URL}/get-instance`);
        const data = await response.json();
        setInstanceData(data);
        setLoading(false);
      } catch (err) {
        console.error("Error calling get-instance:", err);
        setError("Failed to fetch instance data.");
        setLoading(false);
      }
    };

    callMyBackend();
  }, []);

  return (
    <div className={styles.root}>
      <h2>Hello {displayName || 'Wix CLI'}</h2>
      {loading ? (
        <p>Loading instance data...</p>
      ) : error ? (
        <p>{error}</p>
      ) : (
        <div>
          <p>Success!</p>
        </div>
      )}
    </div>
  );
};

const customElement = reactToWebComponent(
  CustomElement,
  React,
  ReactDOM as any,
  {
    props: {
      displayName: 'string',
    },
  }
);

export default customElement;
```

## See also

* [About Site Widget Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/about-site-widget-extensions.md)
* [About App Instances](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances.md)