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, email humans@tiptap.dev. Until it's enabled, keep using the App ID + secret flow described in the Install guide — it continues to work unchanged.

Tiptap Access Control is a new authentication format that replaces the X-App-Id + per-service secret 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 "AI", so existing integrations keep working without changes.

How to enable it

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.
Generate JWTs with aud: "AI", your environment id as iss, and a permissions array listing the actions the token is allowed to perform (see below).
Send the JWT in the Authorization: Bearer <jwt> header. The X-App-Id header is not read on this path.

Permissions

Action	Grants
`AI:Toolkit`	All Server AI Toolkit endpoints (tools, workflows, execute-tool)
`Documents:Write`	Read, write, and comment access to Tiptap Cloud documents. Required when using `experimental_documentOptions` so the AI server can fetch and save documents automatically.

Documents:Write implies read and comment access, so you do not need separate Documents:Read or Documents:Comment permissions for toolkit workflows.

Example token payload

A token for toolkit-only access without document server integration:

{
  "iss": "env_abc123",
  "aud": ["AI"],
  "exp": 1777033105,
  "permissions": [{ "action": "AI:Toolkit", "resource": "*" }]
}

A token that also allows the toolkit to fetch and save Tiptap Cloud documents:

{
  "iss": "env_abc123",
  "aud": ["AI", "Documents"],
  "exp": 1777033105,
  "permissions": [
    { "action": "AI:Toolkit", "resource": "*" },
    { "action": "Documents:Write", "resource": "my-document-id" }
  ]
}

Error responses

When the token is missing a required permission, the service responds 403 Forbidden with:

{
  "message": "Token is missing permission AI:Toolkit.",
  "code": "permission_denied"
}

If the environment's subscription doesn't include the Server AI Toolkit at all, the response is 403 with code: feature_not_available.

Set up authorization with Tiptap Access Control

Install the JWT signing library:

npm install jose

Environment variables

Configure the following environment variables:

# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id
TIPTAP_PRIVATE_KEY=your-private-key-pem

TIPTAP_CLOUD_AI_API_URL: The base URL for the Server AI Toolkit API.
TIPTAP_ENVIRONMENT_ID: Your environment hash ID from the Tiptap dashboard. Used as the iss claim when signing JWTs.
TIPTAP_PRIVATE_KEY: Your ES256 private key (PKCS#8 PEM) from the Tiptap dashboard. Used to sign JWTs server-side.

Create a JWT token

This function generates a JWT for authenticating with the Server AI Toolkit API. Pass a documentId when the Server AI Toolkit should fetch and save Tiptap Cloud documents automatically via experimental_documentOptions.

// lib/server-ai-toolkit/create-jwt-token.ts
import { SignJWT, importPKCS8 } from 'jose'

type CreateJwtTokenOptions = {
  documentId?: string
}

/**
 * Generates a JWT for authenticating with the Server AI Toolkit API
 */
export async function createJwtToken(options: CreateJwtTokenOptions = {}): Promise<string> {
  const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY!, 'ES256')

  const permissions: { action: string; resource: string }[] = [
    { action: 'AI:Toolkit', resource: '*' },
  ]

  if (options.documentId) {
    permissions.push({ action: 'Documents:Write', resource: options.documentId })
  }

  return new SignJWT({ permissions })
    .setProtectedHeader({ alg: 'ES256' })
    .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID!)
    .setAudience(options.documentId ? ['AI', 'Documents'] : ['AI'])
    .setIssuedAt()
    .setExpirationTime('30m')
    .sign(privateKey)
}

Alternative: provide documents directly

If you manage documents in your own storage instead of Tiptap Cloud, omit the documentId option and pass documents directly via the document field in API requests. The token only needs the AI:Toolkit permission.

Call API endpoints

Once authenticated, call the Server AI Toolkit API endpoints. Generate the JWT and set the Authorization header.

When using Tiptap Cloud documents, pass the document ID to include Documents:Write permission.

const jwt = await createJwtToken({ documentId: 'my-document-id' })

const response = await fetch(`${apiBaseUrl}/v3/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwt}`,
  },
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    experimental_documentOptions: {
      documentId,
    },
  }),
})

For complete API documentation, see the REST API reference.

See the Authentication guide for more information about Tiptap Access Control.

PreviouslyInstall

Next upAgents