# Installing the Headless SDK

This guide shows how to add [Solis](https://prismatic.io/docs/embed/headless.md), Prismatic's headless SDK, to your frontend and connect it to Prismatic as a signed-in customer user. After it connects, you can read the marketplace, instances, and connections and render them with your own components.

## Before you begin[​](#before-you-begin "Direct link to Before you begin")

* Your backend must sign a JWT for each signed-in user, as described in [Authenticating embedded users](https://prismatic.io/docs/get-started/embedded-marketplace/authenticate-embedded-users.md). Solis uses the same token as the hosted embedded SDK.
* Solis runs in the browser. It doesn't support server-side rendering: during a server render, the React hooks stay `loading`.

## Install the package[​](#install-the-package "Direct link to Install the package")

Solis has two packages. Install the one that matches your frontend:

| Package                     | Use it when                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `@prismatic-io/solis-react` | Your app uses React 18 or 19. It includes `@prismatic-io/solis-core`, so you don't install both. |
| `@prismatic-io/solis-core`  | Your app uses another framework, or none.                                                        |

* React
* Other frameworks

```bash
npm install @prismatic-io/solis-react@latest

```

```bash
npm install @prismatic-io/solis-core@latest

```

## Connect to Prismatic[​](#connect-to-prismatic "Direct link to Connect to Prismatic")

Solis connects to Prismatic through a hidden iframe that it adds to your page. The iframe never renders anything, and your app never calls Prismatic's API directly. You pass Solis two things:

* **Your Prismatic URL**: `https://app.prismatic.io`, the URL of your [deployment region](https://prismatic.io/docs/configure-prismatic/deployment-regions.md#logging-in-to-additional-regions) (like `https://app.eu-west-1.prismatic.io`), or your [custom white-label domain](https://prismatic.io/docs/configure-prismatic/custom-domains.md).
* **The user's JWT**: The token your backend signed for the signed-in user.

- React
- Other frameworks

Wrap the part of your app that uses Prismatic in `PrismaticProvider`:

Integrations.tsx

```tsx
import { PrismaticProvider } from "@prismatic-io/solis-react";

export function Integrations({ token }: { token: string }) {
  return (
    <PrismaticProvider
      prismaticUrl="https://app.prismatic.io"
      auth={{ token }}
      onError={(error) => console.error("Prismatic session failed", error)}
    >
      <IntegrationsPage />
    </PrismaticProvider>
  );
}

```

Hooks inside the provider share one session and one cache. Until the provider receives a token, the session stays `loading`.

Call `createClient` with your Prismatic URL and the user's JWT:

prismatic.ts

```ts
import { createClient } from "@prismatic-io/solis-core";

export async function connectToPrismatic(token: string) {
  const client = await createClient({
    prismaticUrl: "https://app.prismatic.io",
    jwt: token,
  });
  return client;
}

```

`createClient` resolves once the iframe is ready and throws a `ConnectError` if it can't connect within 30 seconds. Change the limit with the `timeoutMs` option. When the user leaves the page that uses Prismatic, call `client.dispose()` to remove the iframe and release the session.

## Refresh the token[​](#refresh-the-token "Direct link to Refresh the token")

Embedded user JWTs expire, so your app needs to fetch new ones while the user is signed in. When it does, pass the new token to Solis. Solis applies it to the live session, so loaded data stays in place. If the new token belongs to a different user, Solis drops the previous user's data.

* React
* Other frameworks

Pass the new token to `PrismaticProvider` through the `auth` prop.

Call `client.authenticate(newToken)` and make later requests through the handle it returns, or through `client.authenticated`.

## Verify the connection[​](#verify-the-connection "Direct link to Verify the connection")

Confirm that Solis connected and accepted the token by reading the signed-in user:

* React
* Other frameworks

IntegrationsPage.tsx

```tsx
import { useAuthenticatedUser, usePrismatic } from "@prismatic-io/solis-react";

function IntegrationsPage() {
  const session = usePrismatic();
  const user = useAuthenticatedUser();

  if (session.status === "error") {
    return <p>Could not connect: {session.error.message}</p>;
  }
  if (user.status === "loading") return <p>Connecting…</p>;
  if (user.status === "error") return <p>{user.error.message}</p>;

  return <p>Connected to Prismatic as {user.data.email}</p>;
}

```

```ts
const client = await connectToPrismatic(token);
const user = await client.authenticated?.getAuthenticatedUser();
console.log(`Connected to Prismatic as ${user?.email}`);

```

If the session doesn't connect, check that the Prismatic URL matches the region or domain where your organization lives, and that your backend signs the token as described in [Authenticating embedded users](https://prismatic.io/docs/get-started/embedded-marketplace/authenticate-embedded-users.md).

## Next steps[​](#next-steps "Direct link to Next steps")

* [Build a configuration UI with Solis React](https://prismatic.io/docs/embed/headless/react.md)
* [Build a custom marketplace with Solis](https://prismatic.io/docs/get-started/embedded-marketplace/custom-marketplace.md)
* [Build a one-click connect list with Solis](https://prismatic.io/docs/get-started/embedded-marketplace/one-click-connect.md)