> ## 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.

# Quickstart

> Install the Reducto Office SDK for Word documents and set up its license check.

The Office SDK (`@reductoai/docx`) reads, edits, renders and exports Word documents in Node.js and in the browser, without Microsoft Office. You install it with an install token from Studio, and it checks its license with Reducto while it runs.

You need a Reducto account and an API key. You get both in [Studio](https://studio.reducto.ai/).

## How it works

You need two credentials:

* **Install token.** npm uses it to download the SDK. It starts with `rnpm_` and can only download packages.
* **Reducto API key.** The SDK sends it with each license check, and Reducto bills the usage to the key's organization. It is the key you use for the Reducto API.

All the install tokens of your organization share one license. Use one token per laptop or CI system, so you can revoke one without touching the others.

## Install

**1. Create an install token**

In Studio, open **Office SDK** and select **New token**. Give it a name, such as `CI` or `Jane's laptop`.

Studio shows the token once. Copy the `.npmrc` it gives you before you close the dialog.

**2. Add the .npmrc**

Put the lines in `~/.npmrc` on your machine, or in a CI secret. Do not commit the token to git.

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

In CI, keep the token in a secret and write the `.npmrc` at build time:

```bash theme={null}
echo "@reductoai:registry=https://npm.reducto.ai/" >> ~/.npmrc
echo "//npm.reducto.ai/:_authToken=${REDUCTO_NPM_TOKEN}" >> ~/.npmrc
```

**3. Install the package**

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

Check that npm can reach the registry with `npm whoami --registry https://npm.reducto.ai/`.

**4. Set your API key**

The SDK reads `REDUCTO_API_KEY` from the environment.

```bash theme={null}
export REDUCTO_API_KEY=your_api_key
```

## Use it on a server

On Node.js, the SDK reads `REDUCTO_API_KEY` and checks its license with Reducto.

```ts theme={null}
import { readFile } from "node:fs/promises";
import { parseDocx } from "@reductoai/docx";

const doc = await parseDocx(await readFile("contract.docx"));
```

The first document opens only after a good license check. Opening it waits up to 10 seconds for the answer, then fails with `ReductoLicenseError` (`unconfigured`). After that, the SDK checks about every hour in the background, and document calls do not wait for those checks. See [License checks](https://docs.reducto.ai/office/licensing/checks.md).

## Use it in a browser

A browser editor needs a license proxy on your backend. Without it, the editor opens no document (`unproxied`). The browser sends its license checks to your backend, which adds the API key and forwards them to Reducto, so your API key never goes to the browser.

**1. Add the proxy to your backend**

`licenseProxy` returns a standard `fetch` handler (`Request` in, `Response` out). It works in Node.js 18+ and edge runtimes. Mount it under one path, for example `/reducto`.

```ts app/reducto/[...path]/route.ts theme={null}
import { licenseProxy } from "@reductoai/docx/license-proxy";

export const POST = licenseProxy();
```

Set `REDUCTO_API_KEY` on the backend. Put the route behind your app's own login, like any route that uses your API key. Reducto bills usage sent through it to your organization.

**2. Point the editor at the proxy**

Install the browser editor:

```bash theme={null}
npm install @reductoai/docx-editor
```

Then mount it with the proxy's path:

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

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

The proxy forwards only two requests: `POST <path>/-/license` and `POST <path>/-/events`. Anything else gets a `404`. Reducto signs its answers, and the proxy passes them through unchanged, so the SDK can tell if they were changed on the way.

## Network access

The SDK only needs HTTPS (port 443) to one host:

| Where the SDK runs | Allow outbound traffic to |
| - | - |
| Node.js server | `npm.reducto.ai` |
| Browser with `licenseProxy` | Your backend. The backend needs `npm.reducto.ai`. |
| CI, to install | `npm.reducto.ai` |

The first document needs a good license answer. After that, the SDK keeps working for 65 minutes after its last good answer. If it can't reach Reducto for longer, document calls throw `ReductoLicenseError` (`unverified`) until a check gets through. There is no offline mode.

## Billing

Reducto bills Office SDK usage per Session. A Session is one document open in your application. The same document open for up to 60 minutes counts as one Session.

Reducto bills the organization that owns the API key. Installs, CI systems and install tokens cost nothing.

## Revoke an install token

In Studio, open **Office SDK** and select **Revoke** next to the token. New `npm install` runs with that token fail at once. Copies of the SDK that are already installed keep running, because the license belongs to your organization, not to the token.

## Troubleshooting

> [accordion] npm install fails with 401 or 404
>
> npm sent no token, or the token is revoked. Check that `~/.npmrc` has both lines from Studio and that the token starts with `rnpm_`. Run `npm whoami --registry https://npm.reducto.ai/`. If it fails, create a new token in Studio.

> [accordion] ReductoLicenseError: Reducto license unverified
>
> The SDK had no good license answer for 65 minutes. Check that the server can reach Reducto on port 443 (see [Network access](#network-access)), or, in a browser, that `proxyUrl` points at your `licenseProxy` route and that the backend can reach Reducto.

> [accordion] ReductoLicenseError: Reducto license revoked
>
> Your organization's license was revoked. Contact [support@reducto.ai](mailto:support@reducto.ai).

> [accordion] ReductoLicenseError: Your package isn't configured properly
>
> The first document could not open because no license check succeeded. Check that the package was installed with your Studio install token, that `REDUCTO_API_KEY` is set (on the server or the proxy backend) and belongs to the organization that made the install token, and that the server can reach Reducto.

> [accordion] ReductoLicenseError: unproxied, in a browser
>
> The editor was mounted without `proxyUrl`. Add the [proxy](#use-it-in-a-browser) and pass its path as `proxyUrl`.

> [accordion] The proxy returns 404
>
> The proxy only answers `POST` requests whose path ends in `/-/license` or `/-/events`. Check that your route forwards the full path, for example a catch-all route such as `[...path]`.
