Install

Available in Start planBeta

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

Prerequisites

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

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.

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

{
  "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. You do not send an App ID.

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.

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.

Maintaining an existing integration?

The previous App ID and secret flow is documented under Legacy authentication and keeps working.

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

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.

PreviouslyOverview

Next upLive demo