Install

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

Prerequisites

1. Start a free trial or choose a subscription.
2. Set up access to Tiptap's private npm registry.

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 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) 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)

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 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:

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

Example token payload

{
  "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:

{
  "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:

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

Export:

# 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

Next steps

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