---
title: "Install"
description: "Set up credentials and install conversion extensions for importing and exporting documents."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/conversion/getting-started/install"
---

# Install

Set up credentials and install conversion extensions for importing and exporting documents.

Set up credentials and install the conversion extensions for your project.

## Prerequisites

1. Start a [free trial or choose a subscription](https://cloud.tiptap.dev/v2/billing).
2. Set up access to [Tiptap's private npm registry](https://tiptap-docs.lin52025i.qzz.io/guides/pro-extensions.md).

## Authentication

Most conversion extensions and REST API endpoints require a signed JWT. The DOCX export extension is the exception and works without credentials.

Set the `aud` claim to `"Convert"` and grant the format and direction actions the integration uses. To create a key pair and sign a token, see [Authentication](https://tiptap-docs.lin52025i.qzz.io/authentication.md).

### Actions

Each conversion direction has its own action, so a token scoped to exactly the operations a feature needs never silently widens when a new direction is added:

| Action                    | Grants                                             |
| ------------------------- | -------------------------------------------------- |
| `Convert:Import:Docx`     | Import of DOCX                                     |
| `Convert:Export:Docx`     | Export of DOCX                                     |
| `Convert:Import:Markdown` | Import of Markdown                                 |
| `Convert:Export:Markdown` | Export of Markdown                                 |
| `Convert:Export:Doc`      | Export of legacy DOC                               |
| `Convert:Export:Odt`      | Export of ODT                                      |
| `Convert:Export:Epub`     | Export of EPUB                                     |
| `Convert:Export:Pdf`      | Export of PDF                                      |
| `Convert:Fonts`           | Managing the font cache (`/fonts/*`), on-prem only |

Legacy routes without an explicit format (`POST /v2/import`, `POST /v2/export`) check `Convert:Import:Docx` and `Convert:Export:Docx` respectively.

### Example token

```json
{
  "iss": "env_abc123",
  "aud": "Convert",
  "exp": 1777033105,
  "permissions": [
    { "action": "Convert:Import:Docx", "resource": "*" },
    { "action": "Convert:Export:Docx", "resource": "*" },
    { "action": "Convert:Export:Pdf", "resource": "*" }
  ]
}
```

A request to `POST /v2/export/pdf` with this token succeeds. `POST /v2/export/odt` is rejected with a `permission_denied` error naming the missing action.

Send the token in the `Authorization: Bearer <jwt>` header for REST calls, or pass it through the `token` option on the editor extensions. The token is all a request needs.

> **Importing comments:**
>
> Importing a document that contains comments writes them to the Document Server. Include `Documents:Write` alongside your `Convert:Import:*` action so the import can save them. See [cross-service actions](https://tiptap-docs.lin52025i.qzz.io/authentication.md#cross-service-actions).

### Error responses

When the token is missing a required permission, the service responds `403 Forbidden` with:

```json
{
  "message": "Token is missing permission Convert:Export:Pdf.",
  "code": "permission_denied"
}
```

If the environment's subscription doesn't include Convert at all, the response is `403` with `code: feature_not_available`. Upstream cloud errors are mapped through cleanly: `429 rate_limited`, `503 service_unavailable`, and `401 token_expired` / `signature_invalid` so your client can distinguish a bad token from a temporary cloud problem.

> **Maintaining an existing integration?:**
>
> The previous App ID and secret flow is documented under [Legacy authentication](https://tiptap-docs.lin52025i.qzz.io/authentication/legacy.md) and keeps working.

## Install packages

Install the extensions you need for the formats you want to support.

**Import:**

```bash
# DOCX import (editor extension)
npm install @tiptap-pro/extension-import-docx
```

**Export:**

```bash
# DOCX export (editor extension, no auth required)
npm install @tiptap-pro/extension-export-docx

# PDF export
npm install @tiptap-pro/extension-export-pdf

# ODT export
npm install @tiptap-pro/extension-export-odt

# EPUB export
npm install @tiptap-pro/extension-export-epub

# Markdown export
npm install @tiptap-pro/extension-export-markdown
```

> **DOCX export does not require authentication:**
>
> The `@tiptap-pro/extension-export-docx` package handles conversion entirely on the client. No
> token or server calls needed.

## Next steps

Choose your format in the sidebar to see the full setup and configuration guide for each extension and REST API.