---
title: "Install"
description: "Set up credentials and install conversion extensions for importing and exporting documents."
canonical_url: "https://tiptap.dev/docs/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.dev/docs/guides/pro-extensions.md).

## Authentication

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

1. Go to the [Convert settings](https://cloud.tiptap.dev/v2/cloud/convert) page in your Tiptap Cloud account.
2. Copy your **App ID** and **secret key**.
3. Generate a JWT using any JWT tool (e.g., [JWT Builder](https://jwt.io)) for local testing. In production, always generate JWTs server-side to keep your secret safe.

You will pass the JWT and App ID when configuring extensions or making REST API calls. See the format-specific setup guides below for details.

## Tiptap Access Control (preview)

> **Not generally available:**
>
> The Tiptap Access Control authentication format is in preview and is not enabled by default. To request access for your environment, email [humans@tiptap.dev](mailto:humans@tiptap.dev). Until it's enabled, keep using the App ID + JWT flow described above — it continues to work unchanged.

Tiptap Access Control is a new authentication format that replaces the `x-app-id` + per-request `convert/authenticate` round-trip with a single signed JWT carrying explicit permissions. The two formats live side by side: the service routes a request to the new path only when the JWT's audience claim is `"Convert"`, so existing integrations keep working without changes.

### How to enable it

1. Email [humans@tiptap.dev](mailto:humans@tiptap.dev) and ask to enable Tiptap Access Control for your Tiptap Cloud environment. We'll provision the signing key and confirm when your environment is ready.
2. Generate JWTs with `aud: "Convert"`, your environment id as `iss`, and a `permissions` array listing the actions the token is allowed to perform (see below).
3. Send the JWT in the `Authorization: Bearer <jwt>` header. The `x-app-id` header is **not** read on this path.

### Per-format, per-direction permissions

Each conversion direction has its own action, so handing out a token scoped to exactly the operations a feature needs never silently widens later 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 payload

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

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

## 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 JWT,
> App ID, 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.