From 96e24a1f84629d5fc20923bd9865cc85a14f8f40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Berg=C3=A9?= <berge.greg@gmail.com>
Date: Wed, 21 Jan 2026 12:05:14 +0100
Subject: [PATCH] Fix JWT token usage in GitBook embed SDK (#3922)

---
 .changeset/forty-ads-attend.md                |  5 +++
 bun.lock                                      |  1 +
 packages/embed/package.json                   |  2 +
 .../embed/src/client/createGitBook.test.ts    | 38 +++++++++++++++++++
 packages/embed/src/client/createGitBook.ts    |  2 +-
 packages/embed/tsconfig.json                  |  4 +-
 6 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/forty-ads-attend.md
 create mode 100644 packages/embed/src/client/createGitBook.test.ts

diff --git a/.changeset/forty-ads-attend.md b/.changeset/forty-ads-attend.md
new file mode 100644
index 000000000..347495615
--- /dev/null
+++ b/.changeset/forty-ads-attend.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/embed": patch
+---
+
+Fix signed JWT token usage
diff --git a/bun.lock b/bun.lock
index 55b4a89f1..569b3c9d2 100644
--- a/bun.lock
+++ b/bun.lock
@@ -56,6 +56,7 @@
       },
       "devDependencies": {
         "@types/react": "catalog:",
+        "bun-types": "catalog:",
         "react": "catalog:",
         "tsdown": "catalog:",
         "typescript": "catalog:",
diff --git a/packages/embed/package.json b/packages/embed/package.json
index 1cdda9e7b..d2d94aefd 100644
--- a/packages/embed/package.json
+++ b/packages/embed/package.json
@@ -23,6 +23,7 @@
         "react": "*"
     },
     "devDependencies": {
+        "bun-types": "catalog:",
         "@types/react": "catalog:",
         "tsdown": "catalog:",
         "typescript": "catalog:",
@@ -33,6 +34,7 @@
         "build-lib": "tsdown",
         "build-standalone": "bun build src/standalone/index.ts --bundle --minify --outdir=standalone",
         "clean": "rm -rf ./dist",
+        "unit": "bun test",
         "typecheck": "tsc --noEmit",
         "dev": "bun run build -- --watch ./src",
         "publish-to-npm": "../../scripts/publish-if-new.sh"
diff --git a/packages/embed/src/client/createGitBook.test.ts b/packages/embed/src/client/createGitBook.test.ts
new file mode 100644
index 000000000..3ddcd660e
--- /dev/null
+++ b/packages/embed/src/client/createGitBook.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createGitBook } from './createGitBook';
+
+describe('createGitBook.getFrameURL', () => {
+    it('builds the embed URL when the site URL has no trailing slash', () => {
+        const client = createGitBook({ siteURL: 'https://example.com/docs' });
+
+        const url = new URL(client.getFrameURL({}));
+
+        expect(url.origin).toBe('https://example.com');
+        expect(url.pathname).toBe('/docs/~gitbook/embed');
+        expect(url.searchParams.toString()).toBe('');
+    });
+
+    it('handles a trailing slash and adds visitor parameters', () => {
+        const client = createGitBook({ siteURL: 'https://example.com/docs/' });
+
+        const url = new URL(
+            client.getFrameURL({
+                visitor: {
+                    token: 'signed-token',
+                    unsignedClaims: {
+                        role: 'editor',
+                        count: 3,
+                        enabled: false,
+                    },
+                },
+            })
+        );
+
+        expect(url.pathname).toBe('/docs/~gitbook/embed');
+        expect(url.searchParams.get('jwt_token')).toBe('signed-token');
+        expect(url.searchParams.get('visitor.role')).toBe('editor');
+        expect(url.searchParams.get('visitor.count')).toBe('3');
+        expect(url.searchParams.get('visitor.enabled')).toBe('false');
+    });
+});
diff --git a/packages/embed/src/client/createGitBook.ts b/packages/embed/src/client/createGitBook.ts
index fc39c71bb..1f12277e9 100644
--- a/packages/embed/src/client/createGitBook.ts
+++ b/packages/embed/src/client/createGitBook.ts
@@ -43,7 +43,7 @@ export function createGitBook(options: CreateGitBookOptions) {
             url.pathname = `${url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`}~gitbook/embed`;
 
             if (frameOptions.visitor?.token) {
-                url.searchParams.set('token', frameOptions.visitor.token);
+                url.searchParams.set('jwt_token', frameOptions.visitor.token);
             }
 
             if (frameOptions.visitor?.unsignedClaims) {
diff --git a/packages/embed/tsconfig.json b/packages/embed/tsconfig.json
index 37ff33111..92db2d902 100644
--- a/packages/embed/tsconfig.json
+++ b/packages/embed/tsconfig.json
@@ -15,7 +15,9 @@
         "isolatedModules": true,
         "jsx": "react-jsx",
         "incremental": true,
-        "types": []
+        "types": [
+            "bun-types" // add Bun global
+        ]
     },
     "include": ["src/**/*.ts", "src/**/*.tsx"],
     "exclude": ["node_modules"]