Skip to main content

Token in header

When performing the HTTP requests from or to ONLYOFFICE Docs an authorization header with the token is added to validate the request.

The JSON Web Token payload contains the payload object with the request body parameters.

info

In the examples below, example.com represents the server where your document storage service is installed. See the How it works section to learn more about ONLYOFFICE Docs service client-server interactions.

Incoming request​

note

Starting from version 10.0, the token of an incoming request can contain the operation field with the type of the request: command for the document command service, converter for the document conversion service, and docbuilder for the document builder service. If the field is present, it must match the service the request is sent to. These services also no longer accept the token from the editor configuration. How strictly the token is checked is set by the services.CoAuthoring.token.purposeCheck server setting.

warning

It is not recommended to send a signature in the header when performing the HTTP requests to ONLYOFFICE Docs. Send the signature in the body.

Get document status​

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

Sample payload:

{
  "payload": {
    "c": "info",
    "key": "Khirz6zTPdfd7"
  }
}

Request:

curl -X POST "https://documentserver/command" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImMiOiJpbmZvIiwia2V5IjoiS2hpcno2elRQZGZkNyJ9fQ.hGQ8kquQWpg4MQYiSYaIzik0wotP1coAop6QfLruenA" \
  -d '{
    "c": "info",
    "key": "Khirz6zTPdfd7"
  }'

Convert document​

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

Sample payload:

{
  "payload": {
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
  }
}

Request:

curl -X POST "https://documentserver/converter" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImZpbGV0eXBlIjoiZG9jeCIsImtleSI6IktoaXJ6NnpUUGRmZDciLCJvdXRwdXR0eXBlIjoicGRmIiwidGl0bGUiOiJFeGFtcGxlIERvY3VtZW50IFRpdGxlLmRvY3giLCJ1cmwiOiJodHRwOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtZG9jdW1lbnQuZG9jeCJ9fQ.Ec50Gvafu4niR2I1LPgETn1jkvvs1wKm0YeeI1RbRQs" \
  -d '{
    "filetype": "docx",
    "key": "Khirz6zTPdfd7",
    "outputtype": "pdf",
    "title": "Example Document Title.docx",
    "url": "https://example.com/url-to-example-document.docx"
  }'

Document builder​

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

Sample payload:

{
  "payload": {
    "async": true,
    "url": "https://example.com/url-to-example-script.js"
  }
}

Request:

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFzeW5jIjp0cnVlLCJ1cmwiOiJodHRwczovL2V4YW1wbGUuY29tL3VybC10by1leGFtcGxlLXNjcmlwdC5qcyJ9fQ.0_2NH7PCswspvVWcc8W5Fzfbx9dCNvynP9DNlI0qJDU" \
  -d '{
    "async": true,
    "url": "https://example.com/url-to-example-script.js"
  }'

Outgoing requests​

note

Starting from version 10.0, the token of every outgoing request also contains the operation field with the type of the request: callback for the requests to the callbackUrl address and download for the file and document changes downloads. ONLYOFFICE Docs rejects an incoming request whose token contains one of these values.

Callback on close without changes​

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

Sample payload:

{
  "payload": {
    "key": "Khirz6zTPdfd7",
    "status": 4
  },
  "operation": "callback"
}

Request:

curl -X POST "https://example.com/url-to-callback" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImtleSI6IktoaXJ6NnpUUGRmZDciLCJzdGF0dXMiOjR9LCJvcGVyYXRpb24iOiJjYWxsYmFjayJ9.o3l4KlxMeFtaZEY5UQiWuWMktxGEdvjoN9ckHlmGIQs" \
  -d '{
    "key": "Khirz6zTPdfd7",
    "status": 4
  }'

File download​

Validation is performed for outgoing requests to document storage service for file download.

Sample payload:

{
  "payload": {
    "url": "https://example.com/url-to-example-document.docx"
  },
  "operation": "download"
}

Request:

curl -X GET "https://example.com/url-to-example-document.docx" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7InVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtZG9jdW1lbnQuZG9jeCJ9LCJvcGVyYXRpb24iOiJkb3dubG9hZCJ9.gDT6MsJSGJUJyR_BpvixtASOxCKZDO0-pHVuAsSrf9w"

The token includes the payload (the full URL to the document, in the example above it is {"url": "https://example.com/url-to-example-document.docx"}), which is also duplicated in the header as the Host (example.com) and the document address the GET request is sent to (url-to-example-document.docx).

Document changes download​

Validation is performed for outgoing requests to document storage service for document changes data download.

Sample payload:

{
  "payload": {
    "url": "https://example.com/url-to-document-changes.zip"
  },
  "operation": "download"
}

Request:

curl -X GET "https://example.com/url-to-document-changes.zip" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7InVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWRvY3VtZW50LWNoYW5nZXMuemlwIn0sIm9wZXJhdGlvbiI6ImRvd25sb2FkIn0.Mr_bM2onk92qLP2VoqSFhjB3JC4wO1uXtLuw_L5F3j4"

The token includes the payload (the full URL to the document, in the example above it is {"url": "https://example.com/url-to-document-changes.zip"}), which is also duplicated in the header as the Host (example.com) and the document address the GET request is sent to (url-to-document-changes.zip).