Skip to main content

Key concepts

Understanding the following concepts is critical for implementing WOPI client integration. For more details, see the official Microsoft documentation.

Client​

The service that provides file viewing/editing capabilities to users.

The WOPI client sends requests to the WOPI host to:

  • access information about files and folders;
  • access contents of files and folders;
  • change contents of files and folders.

Server / host​

The service that stores files.

The WOPI host responds to WOPI requests from the WOPI client. It returns information about files and file contents in responses. The WOPI host never initiates communication with the WOPI client (except for the initial open request flow).

File ID​

A file ID is a unique string representing the target of WOPI operations (a file or a folder). The host must issue a unique ID for any file used by the WOPI client. The client includes this ID when making requests, so the host must be able to locate a specific file by this ID.

The file ID must:

  • identify a single file;
  • be URL-encoded compliant, because it is primarily passed via the WOPISrc parameter;
  • remain unchanged after editing the file;
  • remain unchanged after moving/renaming the file;
  • remain unchanged after renaming any ancestor folder;
  • remain consistent for all users accessing a shared file.

Access token​

An access token is a security credential used to validate the identity and permissions of the issuer of a WOPI request.

The WOPI host stores files and also knows user permissions, so it must provide an access token to the client. The client returns this token in subsequent requests and the host validates it. If the token is invalid or unauthorized, the host responds with the corresponding HTTP status code.

In an online office scenario, the host generates an access token in advance and passes it to the client via the access_token parameter before the first WOPI request.

WOPI access tokens must follow the specification described here.

Token expiry (access_token_ttl)​

The access_token_ttl property indicates when the WOPI client’s access token expires, represented as the number of milliseconds since January 1, 1970 UTC (JavaScript epoch timestamp). Despite the name, it does not represent the token’s lifetime duration; it is always tied to a specific access token and is not used alone.

We recommend setting access_token_ttl to 10 hours so the token remains valid for 10 hours. The host can also set access_token_ttl to 0, indicating the expiry is infinite or unknown. However, this may cause the client to disable UI prompts for refreshing sessions, which can lead to unexpected data loss when the token expires. Therefore, we strongly recommend specifying a concrete value for access_token_ttl.

Lock​

Locks are an important concept in WOPI and serve two purposes:

  • A lock prevents any entity without a valid lock ID from modifying a file. When a user starts editing a file via a WOPI client, the client typically locks the file to ensure others cannot change it during editing.
  • A lock stores a small piece of temporary metadata called the lock ID. The lock ID is a string up to 1024 ASCII characters.

Therefore, WOPI locks must:

  • be associated with a single file;
  • contain a lock ID string (up to 1024 ASCII characters);
  • block any modification unless the correct lock ID is provided;
  • expire after 30 minutes unless refreshed by subsequent lock calls (see Lock);
  • not be tied to a specific user.

All WOPI operations that modify files (for example, PutFile) include a lock ID parameter, usually passed via the X-WOPI-Lock request header.

WOPI requires the host to compare the lock ID in the request with the file’s current lock ID. If they do not match, the host must return the current lock ID in the X-WOPI-Lock response header. This is critical because WOPI clients rely on it to decide subsequent WOPI calls.

WOPI source URL (WOPISrc)​

The WOPISrc (WOPI Source) is a file-specific URL used to perform WOPI operations. It is composed of the host’s files endpoint URL and a specific file ID, and does not include the access token.

Last updated on