---
title: "Legacy authentication"
description: "Reference for the previous per-service authentication model based on App IDs and per-service secrets. For maintaining and troubleshooting existing integrations."
canonical_url: "https://tiptap.dev/docs/authentication/legacy"
---

# Legacy authentication

Reference for the previous per-service authentication model based on App IDs and per-service secrets. For maintaining and troubleshooting existing integrations.

Before the unified [Authentication](https://tiptap.dev/docs/authentication.md) 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](https://tiptap.dev/docs/authentication/migrate.md).

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

```typescript
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](https://tiptap.dev/docs/collaboration/getting-started/authenticate.md#authorize-per-document) and the [migration mapping](https://tiptap.dev/docs/authentication/migrate.md#collaboration-and-documents).

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

```bash
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](https://tiptap.dev/docs/authentication/migrate.md#conversion).

## 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](https://tiptap.dev/docs/content-ai/capabilities/generation/install.md).

## 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](https://tiptap.dev/docs/authentication/migrate.md).