Set Up ONLYOFFICE JWT Secrets Across Server and Connector

Use one strong JWT secret consistently: configure it on ONLYOFFICE Docs, copy the same value into the connected platform’s ONLYOFFICE settings, and keep JWT validation enabled. Docs 7.2 and later enable JWT by default and generate a secret automatically; changing the secret means every integration must be updated to match it. The exact server-side method depends on whether Docs runs as a Linux package or a Docker container.

What must match?

JWT (JSON Web Token) lets ONLYOFFICE Docs verify signed requests. The document platform and Docs must use the same secret and compatible header settings. The server uses separate token settings for browser configuration and incoming and outgoing service requests; the shared secret values protect those exchanges. Do not put the secret in a public web page, a client-side JavaScript bundle, a support ticket, or a publicly readable source repository.

Before editing, identify your deployment type and record the Docs URL used by your connector. Generate a long, unpredictable secret with a password manager or a cryptographically secure generator. Treat it as a credential, and store it in a restricted configuration store.

Configure a Linux installation

For a package-based Linux installation, edit /etc/onlyoffice/documentserver/local.json. Preserve any existing settings: merge the following keys into the existing JSON rather than replacing the whole file. The example shows the token-validation structure and the three matching secret locations described in the official configuration guide:

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        }
      },
      "secret": {
        "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" },
        "session": { "string": "REPLACE_WITH_YOUR_SECRET" }
      }
    }
  }
}

Replace every placeholder with the exact same secret value. Do not paste the sample placeholder itself. The browser, inbox, and outbox switches are separate; enabling only one does not enable all request validation. Docs 7.2 and later have JWT enabled by default, but explicitly checking these settings helps when auditing an existing configuration or aligning behavior across nodes. For versions before 7.2, the official guide says to enable all three switches.

Validate the JSON syntax before restarting. Then restart the Document Server services so the changes load:

sudo systemctl restart ds-converter ds-docservice ds-metrics

Run the command with an account allowed to manage system services. On Windows, the configuration file is %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json; use the Windows restart instructions in the official guide instead of the Linux command.

Configure Docker without editing the generated config

For the official Document Server Docker image, set JWT through container environment variables. The official guide warns that manually changing the generated local.json can be undone when the container restarts. Set JWT_ENABLED=true and JWT_SECRET in the container creation command or Compose service, then recreate the container so the environment takes effect. Keep the secret in a protected environment file or secret manager and restrict that file’s permissions; avoid committing it to version control.

services:
  onlyoffice:
    image: onlyoffice/documentserver:YOUR_PINNED_TAG
    environment:
      JWT_ENABLED: "true"
      JWT_SECRET: ${ONLYOFFICE_JWT_SECRET}

Define ONLYOFFICE_JWT_SECRET in the deployment environment or protected .env file. Pin a tested image tag rather than relying on latest, and check the documentation for the exact tag you run. After changing environment values, recreate the container using your normal deployment process. A simple restart may leave the old environment in place.

Update the connector and protect the secret

Open the integration settings in the platform that connects to ONLYOFFICE Docs, such as Nextcloud or another supported connector. Enter the same JWT secret in its secret-key field and save. Also confirm the configured Document Server URL and, if the connector exposes it, the authorization header. The default header in ONLYOFFICE Docs is Authorization; change it only when both sides are configured to use the same alternative.

A secret mismatch commonly appears as an invalid-token or authorization error when opening or saving a document. A mismatch can also happen when only one Docs node behind a load balancer has been updated. If you operate multiple nodes, synchronize the same secret and token settings across all nodes before sending traffic to them. Roll out changes in a controlled window: update Docs and the connector together, and expect existing editor sessions or requests signed with the old value to fail during the transition.

Anyone who can read the secret can create tokens that the server may accept. Limit access to configuration files and deployment variables, use encrypted transport for the connector-to-Docs connection, and rotate the secret if it may have been exposed. Rotation requires updating all Docs nodes and the connector to the new value; do not leave old credentials in checked-in files or logs.

Verify the configuration

• Confirm the Docs service or container is running after the configuration change.
• For a Docker deployment, run sudo docker exec <container_name> sudo documentserver-jwt-status.sh to inspect JWT status. Use the actual container name. This helper is documented for Docker; do not assume it is available in every package installation.
• Open a document through the connected platform, make a small harmless edit, and save it. Confirm both the editor opens and the platform receives the saved change.
• If authentication fails, compare the server and connector secret character for character, check that all relevant token switches are enabled, and verify the request header configuration.

The official configuration guide is the authority for supported settings and version behavior. Consult ONLYOFFICE’s JWT configuration documentation and the official Docker installation parameters for the precise version you deploy.