Request with token in body

When performing the HTTP requests from ONLYOFFICE Document Server the token is added to the parameters to validate the data. When performing the HTTP requests to ONLYOFFICE Document Server the token must be added to the parameters to validate the data.

Starting from version 5.2, it is possible to use the token in body parameters with Document Server. To enable it set the services.CoAuthoring.token.inbox.inBody and services.CoAuthoring.token.outbox.inBody in configuration file to true.

Starting from version 7.1, these parameters are deprecated. Now the incoming requests use the token in body if it exists. Otherwise, the header token is taken. To specify what is used next to validate the data, services.CoAuthoring.server.tokenRequiredParams must be added to the local.json configuration file. If it is true, only the token data is used. Otherwise, the opened request part is merged with the token data.

The outgoing requests use both the token in body and token in header. They can be different. For example, the information about version history can be removed from the header token because of the size limit of the token in header.

Token in body is used for POST requests only. For the GET requests token in header is used.

Parameters

ParameterDescriptionTypeExample
services.CoAuthoring.token.inbox.inBodySpecifies the enabling the token validation in the request body to the document command service, document conversion service and document builder service.booleanfalse
services.CoAuthoring.token.outbox.inBodySpecifies the enabling the token generation for the request body by document editing service to document storage service.booleanfalse

The payload for the JSON Web Token contains the request body parameters.

Incoming request

  • Request to receive the status of the edited document

    Validation is performed for incoming requests with the commands from the document storage service to the document command service.

    Sample parameters of request to receive the status of the edited document

    1. {
    2. "c": "info",
    3. "key": "Khirz6zTPdfd7"
    4. }

    These parameters must be encoded into the token so that the request looked like this:

    Sample of request to receive the status of the edited document

    1. POST coauthoring/CommandService.ashx HTTP/1.1
    2. Host: documentserver
    3. Content-Type: application/json
    4. {
    5. "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjIjoiaW5mbyIsImtleSI6IktoaXJ6NnpUUGRmZDcifQ.r_6sThjFABsHMNHhkVdHDSz4jwkbXRQNYdvawkBGJgg"
    6. }

    As you can see there is no need to include the above parameters into the request body, as all of them are already encoded into the token and sent within it.

  • Request to convert the document

    Validation is performed for incoming requests with the commands from the document storage service to the document conversion service.

    Sample parameters of request to convert the document

    1. {
    2. "filetype": "docx",
    3. "key": "Khirz6zTPdfd7",
    4. "outputtype": "pdf",
    5. "title": "Example Document Title.docx",
    6. "url": "https://example.com/url-to-example-document.docx"
    7. }

    Where the example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on Document Server service client-server interactions.

    Sample of request to convert the document

    1. POST ConvertService.ashx HTTP/1.1
    2. Host: documentserver
    3. Content-Type: application/json
    4. {
    5. "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxldHlwZSI6ImRvY3giLCJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwib3V0cHV0dHlwZSI6InBkZiIsInRpdGxlIjoiRXhhbXBsZSBEb2N1bWVudCBUaXRsZS5kb2N4IiwidXJsIjoiaHR0cDovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLWRvY3VtZW50LmRvY3gifQ.U-YAfuuy7clWjn-xOncfJ-sxVG5DlcYn0AOzJYkoR0M"
    6. }

    Where the example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on Document Server service client-server interactions.

  • Request to document builder service

    Validation is performed for incoming requests with the commands from the document storage service to the document builder service.

    Sample parameters of request to document builder service

    1. {
    2. "async": true,
    3. "url": "https://example.com/url-to-example-script.docbuilder"
    4. }

    Where the example.com is the name of the server where document storage service are installed. See the How it works section to find out more on Document Server service client-server interactions.

    Sample of request to document builder service

    1. POST docbuilder HTTP/1.1
    2. Host: documentserver
    3. Content-Type: application/json
    4. {
    5. "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3luYyI6dHJ1ZSwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tZXhhbXBsZS1zY3JpcHQuZG9jYnVpbGRlciJ9.dzoTbRzSMa95Fpg34CjnF3ZUPdGA2CnBedFL_qOOxAs"
    6. }

    Where the example.com is the name of the server where document storage service are installed. See the How it works section to find out more on Document Server service client-server interactions.

Outgoing requests

  • Request to “callbackUrl” address by document editing service when the last user closed the document for editing without changes

    Validation is performed for outgoing requests to “callbackUrl“ address by document editing service.

    Sample parameters of request to “callbackUrl” address by document editing service when the last user closed the document for editing without changes

    1. {
    2. "key": "Khirz6zTPdfd7",
    3. "status": 4
    4. }

    Sample of request to “callbackUrl” address by document editing service when the last user closed the document for editing without changes

    1. POST url-to-callback.ashx HTTP/1.1
    2. Host: example.com
    3. Content-Type: application/json
    4. {
    5. "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJLaGlyejZ6VFBkZmQ3Iiwic3RhdHVzIjo0fQ.gCyNKPpg6ISAnhvFQmRiY6BRqG6WPcEGgnK79hREdkU"
    6. }

    Where the example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on Document Server service client-server interactions.

    When performing the GET requests from ONLYOFFICE Document Server an authorization header with the token is added.