The document security token is not correctly formed. How do I correctly form it?

Docs
1

I’m trying out the document server. I installed the developer version of the docker image to test with using
sudo docker run -i -t -d -p 80:80 --restart=always onlyoffice/documentserver-de

Then I looked up the JWT secret that it generated using
docker exec fa3de342eca4 sudo documentserver-jwt-status.sh
which turned out to be ZUFWiLvQ7tnJzaagPhd0zURDH544Eblp
(This is all on localhost and ephemeral, so I don’t care about sharing it).

I confirmed that the document server is alive on http://localhost/welcome/. That page comes up just fine.

I then created a simple html page based on the sample here. Opening file | ONLYOFFICE
and it looks like this:

<html>
<head>
	<script type="text/javascript" src="http://localhost//web-apps/apps/api/documents/api.js"></script>
</head>
	<body>
		<div id="placeholder"></div>
		
		
		<script>
			const config = {
		  document: {
			fileType: "docx",
			key: "Khirz6zTPdfd7",
			title: "Example Document Title.docx",
			url: "c:\mylocalfile.docx",
		  },
		  documentType: "word",
		  token:"ZUFWiLvQ7tnJzaagPhd0zURDH544Eblp",
		};
		
		const docEditor = new DocsAPI.DocEditor("placeholder", config);
		</script>
	</body>
</html>

But when I open that html file, I get the error “The document security token is not correctly formed. Please contact your document server administrator.”.

In the docker logs I see this entry:

[2025-09-15T17:24:42.542] [WARN] [localhost] [Khirz6zTPdfd7] [userId] nodeJS - checkJwt error: name = JsonWebTokenError message = jwt malformed token = ZUFWiLvQ7tnJzaagPhd0zURDH544Eblp

Can someone please explain what I’m doing wrong?

2

Hello @jonathan.janssen,
Please take a look:

This is not your token, but the secret key your token must be signed with. The token must be generated according to jwt.io standards.

3

Ok. What signing algorithm should be used? It looks like that secret key isn’t long enough for any of the standards on https://www.jwt.io/ for example, even hs256 required at least a 256 bit key?

4

The Document Server uses HS256 algorithm by default.

This is only a limitation of the sample token building page. Here you can build a token with no 256 bit limitation for the secret: https://jwt.lannysport.net/

You can also take a look at out integration samples where JWT is properly handled:

5

OK. I installed the windows server version to play around with locally, the C:\Program Files\ONLYOFFICE\DocumentServer\config\local.json has this secret defined:

"browser": {
          "string": "aM0DPwmSjoblen7pG5pfUhfFokkK84"
        },

I paste that key into https://jwt.lannysport.net/ and get a token like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.5z1q-jlF33fWibwKb5g-9bKctQG8Rjx7Hs91GySoJoY

Which I then paste into the sample page so it looks like this:

<html>
<head>
	<script type="text/javascript" src="http://localhost//web-apps/apps/api/documents/api.js"></script>
</head>
	<body>
		<div id="placeholder"></div>
		
		
		<script>
			const config = {
		  document: {
			fileType: "docx",
			key: "Khirz6zTPdfd7",
			title: "Example Document Title.docx",
			url: "c:\mylocalfile.docx",
		  },
		  documentType: "word",
		  token:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.5z1q-jlF33fWibwKb5g-9bKctQG8Rjx7Hs91GySoJoY",
		};
		
		const docEditor = new DocsAPI.DocEditor("placeholder", config);
		</script>
	</body>
</html>

But I still get the same error “The document security token is not correctly formed. Please contact your document server administrator.”. What am I doing wrong?

6

Have you read the page from the documentation I linked earlier?

This is a sample token copied from the token generation page and it is not correct to use it when initializing the editor. The payload of the token must contain editor config parameters listed in the above article. You can also copy the sample token from the article, paste it to jwt.lannysport.net and see how the payload must look like.

If you don’t need JWT in your integration, you can re-deploy the container with the JWT_ENABLED environment variable set to false.

This won’t work because the document must be provided via url, not filepath. You need to use some file server and generate links to your files so that the Document Server is able to download them for editing.

7

Thank your for your help, I think I am beginning to understand. I apologize for my ignorance. I’ve not had to generate JWTs myself like this before. From the Browser | ONLYOFFICE page I created a simple C# web app to generate the tokens and pass them into the editor.
I used the code from here Signature | ONLYOFFICE to generate the token.
I created a token that looks like this:

{
  "document": {
    "key": "Khirz6zTPdfd7",
    "permissions": {
      "comment": true,
      "commentGroups": {
        "edit": [
          "Group2",
          ""
        ],
        "remove": [],
        "view": ""
      },
      "copy": true,
      "deleteCommentAuthorOnly": false,
      "download": true,
      "edit": true,
      "editCommentAuthorOnly": false,
      "fillForms": true,
      "modifyContentControl": true,
      "modifyFilter": true,
      "print": true,
      "review": true,
      "reviewGroups": [
        "Group1",
        "Group2"
      ]
    },
    "url": "https://localhost:7113/Home/GetDoc/1"
  },
  "editorConfig": {
    "callbackUrl": "https://localhost:7113/Home/SaveDocCallback",
    "mode": "edit"
  }
}

header:
{
  "typ": "JWT",
  "alg": "HS256"
}

signature:
UIIxcOSCbDHyY2PD4kpPWt9sl_1LG3nHTX2GEArU634

raw: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkb2N1bWVudCI6eyJrZXkiOiJLaGlyejZ6VFBkZmQ3IiwicGVybWlzc2lvbnMiOnsiY29tbWVudCI6dHJ1ZSwiY29tbWVudEdyb3VwcyI6eyJlZGl0IjpbIkdyb3VwMiIsIiJdLCJyZW1vdmUiOltdLCJ2aWV3IjoiIn0sImNvcHkiOnRydWUsImRlbGV0ZUNvbW1lbnRBdXRob3JPbmx5IjpmYWxzZSwiZG93bmxvYWQiOnRydWUsImVkaXQiOnRydWUsImVkaXRDb21tZW50QXV0aG9yT25seSI6ZmFsc2UsImZpbGxGb3JtcyI6dHJ1ZSwibW9kaWZ5Q29udGVudENvbnRyb2wiOnRydWUsIm1vZGlmeUZpbHRlciI6dHJ1ZSwicHJpbnQiOnRydWUsInJldmlldyI6dHJ1ZSwicmV2aWV3R3JvdXBzIjpbIkdyb3VwMSIsIkdyb3VwMiJdfSwidXJsIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NzExMy9Ib21lL0dldERvYy8xIn0sImVkaXRvckNvbmZpZyI6eyJjYWxsYmFja1VybCI6Imh0dHBzOi8vbG9jYWxob3N0OjcxMTMvSG9tZS9TYXZlRG9jQ2FsbGJhY2siLCJtb2RlIjoiZWRpdCJ9fQ.UIIxcOSCbDHyY2PD4kpPWt9sl_1LG3nHTX2GEArU634

My html:

<div class="text-center">
	<div id="placeholder"></div>
</div>
<script type="text/javascript" src="http://localhost//web-apps/apps/api/documents/api.js"></script>

<script>
		const config = {
	  document: {
		fileType: "docx",
		key: "Khirz6zTPdfd7",
		title: "Example Document Title.docx",
		url: "https://localhost/Home/GetDoc/1",
	  },
	  documentType: "word",
	  token:"raw token from above",
	};

	const docEditor = new DocsAPI.DocEditor("placeholder", config);
</script>

The editor starts to load, but I quickly get this error: “You are trying to perform an action you do not have rights for. Please contact your Document Server administrator.”
I checked the logs in C:\Program Files\ONLYOFFICE\DocumentServer\Log\docservice and DocService_20250916.out.log just has some lines that look like this:
[2025-09-16T14:13:00.132] [WARN] [localhost] [Khirz6zTPdfd7] [uid-1758050880068] nodeJS - fillDataFromJwt token has modified permissions
[2025-09-16T14:13:00.132] [WARN] [localhost] [Khirz6zTPdfd7] [uid-1758050880068] nodeJS - fillDataFromJwt return false

https://jwt.lannysport.net/ tells me this token has an invalid signature. Do you know what I’m doing wrong? Thanks so much!

8

You have to set the same parameters with the same values in your editor config and in token’s payload. The whole point of signing the editor config with JWT is to prevent an unwanted meddling with the editor configuration so that users cannot bypass any limitations that you set via permissions or mode.
When a request to open a document is received, the server compares parameter values in both editor config and the token, and if any mismatch is found, the access to the editor is restricted.

To see this in practice, please install any integration sample that I linked earlier or use the embedded one (instructions on enabling the embedded Example are available at the Welcome page of your document server). You can open any document in the example and analyze the page code, both editor config and token will be present there.

9

It will show this caption until you enter the secret key into the signature field.