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

# Set up

You need an install token for all projects. Then you add one more item, which depends on where the package runs:

| Where the package runs | What you add |
| - | - |
| All projects | An install token in `.npmrc` |
| A server (Node, a worker, a script) | `REDUCTO_API_KEY` in its environment |
| A browser editor | The license proxy on your backend, and `proxyUrl` when you mount the editor |

## 1. Install with an install token

An install token (`rnpm_…`) lets `npm install` download the `@reductoai/*` packages. Make one on the Office SDK page in Reducto Studio.

Studio gives you two lines for `.npmrc`:

```ini theme={null}
@reductoai:registry=https://npm.reducto.ai/
//npm.reducto.ai/:_authToken=rnpm_...
```

Then install as usual:

```sh theme={null}
npm install @reductoai/docx
```

If `npm install` fails with `403`, your lockfile or `package.json` asks for a version that your token cannot install. To fix it, run `npm install @reductoai/docx`.

About tokens:

* **Make one token for each machine or CI job.** Give it a label that tells which one. There is no limit on the number of tokens.
* **You see the token one time only.** If you lose it, make a new one.
* **All tokens of your organization install the same package.** Lockfile hashes are the same on all machines.
* **When you revoke a token, new installs with it fail.** Copies that you installed before continue to work.
* Self-serve tokens install `@reductoai/docx`, `@reductoai/docx-editor`, `@reductoai/viewer` and `@reductoai/portable-fonts`. The PowerPoint and Excel packages are in private preview with alpha customers. [Contact us](https://reducto.ai/contact?source=docs_office_licensing) to get access.

## 2. On a server: set `REDUCTO_API_KEY`

In Node, the package reads `REDUCTO_API_KEY` from the environment. You do not change your code:

```sh theme={null}
REDUCTO_API_KEY=<your API key> node edit.mjs
```

Use a key from the same Reducto organization that made the install token.

A server that runs a copy not installed through your install token, such as a prebuilt image, reads its license from `REDUCTO_LICENSE`. Copy the JSON from `node_modules/@reductoai/docx/reducto-license.js` of an install made with your install token:

```sh theme={null}
REDUCTO_LICENSE='{"id":"lic_…","endpoint":"https://npm.reducto.ai/-/license"}' REDUCTO_API_KEY=<your API key> node edit.mjs
```

The license in the package wins over `REDUCTO_LICENSE`. Either way, nothing opens until Reducto accepts it.

## 3. In a browser: add the license proxy

Do not put your Reducto API key in a page, because all users can read it. A browser editor sends its license traffic to your backend, and your backend adds the key. Without a proxy, a browser editor does not run.

**On your backend**, add `licenseProxy()` behind your own login check. It forwards only license checks and usage reports to Reducto and adds your API key. It answers `404` to all other requests. A Next.js route:

```ts theme={null}
// app/reducto/[...path]/route.ts
import { licenseProxy } from "@reductoai/docx/license-proxy";
import { getSession } from "@/lib/auth"; // your app's login check

const proxy = licenseProxy();

export async function POST(request: Request) {
  if (!(await getSession(request))) {
    return new Response("unauthorized", { status: 401 });
  }
  return proxy(request);
}
```

`licenseProxy()` returns a `(request: Request) => Promise<Response>` function. It works without changes in Next.js route handlers, Hono, Cloudflare Workers, Deno and Bun. Options:

| Option | Default |
| - | - |
| `apiKey` | `process.env.REDUCTO_API_KEY` |
| `upstream` | `https://npm.reducto.ai` |
| `fetch` | The global `fetch` |

Express does not give you a `Request`, so wrap the proxy:

```ts theme={null}
import express from "express";
import { licenseProxy } from "@reductoai/docx/license-proxy";

const proxy = licenseProxy();
const app = express();

app.post(
  ["/reducto/-/license", "/reducto/-/events"],
  requireLogin, // your app's login middleware
  express.text({ type: "*/*" }),
  async (req, res) => {
    const answer = await proxy(
      new Request(`http://localhost${req.path}`, {
        method: "POST",
        headers: { "content-type": req.get("content-type") ?? "text/plain" },
        body: req.body,
      }),
    );
    res
      .status(answer.status)
      .type(answer.headers.get("content-type") ?? "application/json")
      .send(await answer.text());
  },
);
```

**In the page**, give the route's base path as `proxyUrl`:

```ts theme={null}
import { mountDocxEditor } from "@reductoai/docx-editor";

mountDocxEditor("#editor", { proxyUrl: "/reducto" });
```

If you use the headless editor model, not `mountDocxEditor`, call `useProxy("/reducto")` from `@reductoai/docx-editor` one time at startup.

> [!WARNING]
>
> The proxy is required. A browser editor without one sends no license traffic and opens no document: it shows "Your package isn't configured properly."

## Firewalls and networks with no internet access

The package connects only to `npm.reducto.ai`, over HTTPS on port 443. If your network blocks outbound traffic, allow this host:

| Machine | Why it connects to `npm.reducto.ai` |
| - | - |
| CI and build machines | `npm install` |
| Servers that run the package, or the backend with the license proxy | License checks and usage reports, at least one time in 65 minutes |
| Browsers that use the proxy | They do not connect. They send traffic only to your backend |

**Allow the hostname, not IP addresses.** `npm.reducto.ai` is served through Cloudflare, and its IP addresses can change without notice. If your firewall accepts only IP ranges, allow [Cloudflare's published ranges](https://www.cloudflare.com/ips/).

> [!WARNING]
>
> There is no offline license. If a system cannot connect to `npm.reducto.ai` for more than 65 minutes, the package stops with `ReductoLicenseError` (`unverified`). For an air-gapped network, contact [support@reducto.ai](mailto:support@reducto.ai) before you deploy.

## Make sure that the setup works

1. Open a document. The first open waits for a good license check. If the document does not open and you see "Your package isn't configured properly.", see [Troubleshooting](https://docs.reducto.ai/office/licensing/troubleshooting.md).
2. Look at the console. If there are no warnings from Reducto, the setup is correct. [Troubleshooting](https://docs.reducto.ai/office/licensing/troubleshooting.md) lists all warnings.
