Import and Export to Word On-Premises authorization

To enable authorization, set up the SECRET_KEY environment variable during the installation.

If the SECRET_KEY variable is set, then all requests must have a header with a JWT (JSON Web Token) signed with this key. The token should be passed as a value of the Authorization header for each request sent to the Import and Export to Word REST API.

# Generating the token

We highly recommend using the libraries listed on jwt.io to generate the token. The token is considered valid, when:

• it is signed with the same SECRET_KEY as passed to the Import and Export to Word On-Premises instance,
• it was created within the last 24 hours,
• it is not issued in the future (e.i. the iat timestamp cannot be newer than the current time),
• it has not expired yet.

The tokens for the Import and Export to Word On-Premises do not require any additional claims, such as the environment ID (which is specific for Collaboration Server On-Premises), so you can create the token with an empty payload.

If your use case involves sending requests from your backend server, then you can generate JWT tokens locally, as it is done in our request example.

In the case of editor plugins or other frontend usages, you should create a token endpoint, that returns a valid JWT token for authorized users. Here you can find an example of an token endpoint implementation.

# Using editor plugins

The are are two plugins available for CKEditor 5: Export to Word and Import from Word. The plugins will automatically request the token from the given tokenUrl variable and will set the Authorization header when making an export request. Refer to the respective guides for details on adding the Export to Word and Import from Word features to your WYSIWYG editor!

# Request example with an Authorization header

The following example presents a request that generates a valid JWT token and sets it as an Authorization header:

const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const SECRET_KEY = 'secret';

const token = jwt.sign( {}, SECRET_KEY, { algorithm: 'HS256' } );

const data = {
   html: "<p>I am a teapot</p>",
   css: "p { color: red; }",
};

const config = {
   headers: {
      Authorization: token
   },
   responseType: 'arraybuffer',
};

axios.post( 'http://localhost:8080/v1/convert', data, config )
   .then( response => {
      fs.writeFileSync('./file.docx', response.data, 'binary');
   } ).catch( error => {
      console.log( error );
   } );

SECRET_KEY – this is the key what has been passed to the Import and Export to Word On-Premises instance.

Please refer to the Import and Export to Word REST API documentation to start using the service.

Note: If you use API clients like Postman or Insomnia, then set the JWT token as an Authorization header in the Headers tab. Do not use the built-in token authorization as this will generate invalid header with a Bearer prefix added to the token.