Legacy authentication

Before the unified Authentication model, each Tiptap service was authenticated on its own. You copied a per-service App ID and secret from the dashboard and signed a service-specific JWT. This page is a reference for those integrations.

Still supported

Existing integrations keep working without changes. A request that uses the previous format is routed to the previous path automatically, so you can migrate on your own schedule. When you are ready, see Migrate to the new authentication.

How the previous model worked

Each service had its own credentials and its own token shape:

Service	Credentials	Token
Collaboration and Documents	Collaboration secret	JWT signed with the secret, carrying document-access claims
Conversion	App ID and secret (Convert settings)	JWT in `Authorization`, App ID in the `X-App-Id` header
Content AI	App ID and secret (AI settings)	JWT signed with the secret, no extra claims

Collaboration and Documents

You signed a JWT with your Collaboration secret. The payload listed which documents a user could reach and at what level, through allowedDocumentNames, readonlyDocumentNames, and commentDocumentNames.

import jsonwebtoken from 'jsonwebtoken'

const data = {
  sub: 'your_local_user_identifier',
  allowedDocumentNames: ['user-specific-document-1', 'user-specific-document-2'],
}

const jwt = jsonwebtoken.sign(data, 'your_secret')

Access patterns:

Full access. Omit allowedDocumentNames to grant access to every document.
Specific documents. List names in allowedDocumentNames.
Read-only. List names in readonlyDocumentNames.
Comment only. List names in commentDocumentNames alongside read-only access.
Wildcards. Use patterns like project-alpha/* in allowedDocumentNames to match a group.

For the equivalent in the new model, see Authorize per document and the migration mapping.

Conversion

You retrieved an App ID and secret from the Convert settings page, signed a JWT with the secret, and sent both with each REST request:

Authorization: Bearer YOUR_JWT
X-App-Id: YOUR_APP_ID

For the editor extensions you passed the same appId and token options. For the new model, see Migrate to the new authentication.

Content AI

You retrieved an App ID and secret from the AI settings page and signed a JWT with the secret. The App ID and token were passed to the AI extensions. REST requests carried the JWT in Authorization with the App ID in X-App-Id. See Content AI install.

Troubleshooting

A token that used to work is now rejected. Check the exp claim. Short-lived tokens are validated continuously, so an expired token is refused on the next check.
401 on the REST API. Confirm the secret used to sign the token matches the one shown in the service settings, and that the App ID is sent in X-App-Id.
403 with a permission or feature error. The environment's subscription may not include the service. Confirm the plan in the dashboard.

When you are ready to consolidate these per-service tokens into one, see Migrate to the new authentication.

PreviouslyMigrate from legacy

Next upEditor