> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed spaces

> Show a project's spaces in your application, themed to match it, for your own signed-in users.

An embedded space runs in a sandboxed frame on Tilde's spaces host. It gets data only through the project's ontology, with short-lived tokens for the user your server names. The project's policies decide whether that user may open the space and what data they see.

## Server

Install the server package and mount its handler:

```bash theme={"system"}
npm install @trytilde/embed-server
```

```ts lib/tilde.ts theme={"system"}
import { createEmbed } from "@trytilde/embed-server";

export const embed = createEmbed({
  apiKey: process.env.TILDE_EMBED_KEY!,
  resolveIdentity: async (request) => {
    const user = await getSession(request); // your authentication
    if (!user) return null;
    return { id: user.id, groups: [user.customerSlug], attributes: { customer: user.customerId } };
  },
});
```

With Next.js, create `app/api/tilde/[...path]/route.ts`:

```ts theme={"system"}
import { createEmbedRouteHandlers } from "@trytilde/embed-server/next";
import { embed } from "@/lib/tilde";

export const { GET, POST, DELETE } = createEmbedRouteHandlers(embed);
```

With another framework, pass each request below `/api/tilde/` to `embed.handle(request)`. It takes and returns standard `Request` and `Response` objects.

`resolveIdentity` must read your verified server session. Return `null` to refuse the request.

## Browser

```bash theme={"system"}
npm install @trytilde/embed
```

```ts theme={"system"}
import { mountSpace } from "@trytilde/embed";

const space = mountSpace(document.getElementById("pipeline")!, {
  environment: "<environment id>",
  space: "pipeline",
});
```

In React:

```tsx theme={"system"}
import { Space } from "@trytilde/embed/react";

<Space environment="<environment id>" space="pipeline" />;
```

Find the environment ID on the project's **Environments** tab. The space ID is its folder name under `spaces/`.

## Theme

Pass theme tokens to match your application. Each token takes any CSS value.

```ts theme={"system"}
mountSpace(element, {
  environment: "<environment id>",
  space: "pipeline",
  theme: {
    scheme: "light",
    tokens: { accent: "#6d28d9", canvas: "#ffffff", ink: "#111827", radius: "12px", font: "Inter, sans-serif" },
  },
});
```

| Token | Styles |
| - | - |
| `canvas`, `surface` | Page and card backgrounds |
| `ink`, `muted` | Text |
| `line` | Borders |
| `accent`, `good`, `critical` | Highlights and status colours |
| `series-1` to `series-5` | Chart series |
| `radius`, `font` | Corner radius and font family |

Call `space.setTheme(theme)` to change it later, for example when your app switches to dark mode.

## Size, links, and actions

The frame sizes itself to its content. Set `autoResize: false` and `height` for a fixed size.

A space cannot navigate your page itself. Its pages call `navigate` and `emit` from `@tilde/spaces`, and your app decides what happens:

```tsx spaces/pipeline/index.tsx theme={"system"}
import { emit, navigate } from "@tilde/spaces";

<button onClick={() => navigate(`/customers/${row.id}`)}>Open</button>;
<button onClick={() => emit("invoice.selected", { id: row.id })}>Select</button>;
```

```ts theme={"system"}
mountSpace(element, {
  environment: "<environment id>",
  space: "pipeline",
  onNavigate: (to) => router.push(to),
  onEvent: (name, detail) => handle(name, detail),
});
```

Spaces built before these features were added keep working, without resizing or events. Deploy the project again to rebuild them.

## Call the ontology yourself

To render the ontology's data with your own components, get a token for the user on your server and call the environment's API:

```ts theme={"system"}
const { token, gatewayUrl, expiresAt } = await embed.ontologyToken(user, "<environment id>");
```

The token lasts five minutes and carries the same user, groups, and attributes, so the same policies apply.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.