GetNewAccessToken

POST /wopibootstrapper

The GetNewAccessToken operation is used to retrieve a fresh WOPI access token for a given resource (i.e. a file or container), provided the caller has a valid OAuth 2.0 token.

This operation is called by OAuth-capable WOPI clients, such as Microsoft 365 for mobile, to refresh WOPI access tokens when they expire.

Request Headers

• X-WOPI-EcosystemOperation - The string GET_NEW_ACCESS_TOKEN. Required.

• X-WOPI-WopiSrc - The WopiSrc for the file or container. Required.

  Important

  To reduce the likelihood of token spoofing or other unauthorized access, hosts must validate the URL provided in the X-WOPI-WopiSrc header. The bootstrapper must only provide a WOPI access token if the requested WopiSrc exists and the user is authorized to access it. If not, or if the X-WOPI-WopiSrc header is not present, the host should return a 404 Not Found response as described below.

  Important

  In addition, the Microsoft M365 for Mobile apps on both iOS (version 2.62 and later) and Android (version 16.0.15330 and later) and the Office desktops apps (applicable for CSPP Plus integrations) will also validate that the resource specified by X-WOPI-WopiSrc is in a trusted domain (See Onboarding information). Any WOPI requests for resources outside of trusted domains will fail.

• Authorization – A string in the format Bearer: <TOKEN>, where <TOKEN> is a Base64-encoded OAuth 2.0 token. If this header is missing, or the token provided is invalid, the host must respond with a 401 Unauthorized response and include the WWW-Authenticate header as described in WWW-Authenticate response header format.

Response Headers

• WWW-Authenticate – A string value formatted as described in WWW-Authenticate response header format. This header should only be included when responding with a 401 Unauthorized.

Status Codes

• 200 OK – Success

• 401 Unauthorized – Authorization failure; when responding with this status code, hosts must include a WWW-Authenticate response header with values as described in WWW-Authenticate response header format

• 404 Not Found – Resource not found/user unauthorized

• 500 Internal Server Error – Server error

Response

The response to a GetNewAccessToken call is JSON containing the following required properties:

• Bootstrap - The contents of this property should be the response to a Bootstrap call.

• AccessTokenInfo - The contents of this property should be a the nested JSON-formatted object with the following properties:

• AccessToken - A string access token for the file specified in the X-WOPI-WopiSrc request header.

• AccessTokenExpiry - A long value representing the time that the access token provided in the response will expire. See access_token_ttl for more information on how this value is defined.

Sample response:

{
  "Bootstrap": {
    "EcosystemUrl": "http://.../wopi*/ecosystem?access_token=<ecosystem_token>",
    "UserId": "User ID",
    "SignInName": "user@contoso.com",
    "UserFriendlyName": "User Name"
  },
  "AccessTokenInfo": {
    "AccessToken": "1234567890abcdef",
    "AccessTokenExpiry": 1234567890
  }
}