Introduction

The Workspace 365 Provisioning API is intended for provisioning and managing Workspace 365 resources. The API uses a REST-ish interface meaning instead of calling Actions/Methods, you define the Action you want to perform on a resource via the HTTP METHOD (i.e. GET, POST, PUT & DELETE) and uses JSON as its data protocol.

Prerequisites

In order to access the Provisioning API, a so called Provisioning Key needs to be provided with each request.

This key is given during the launch of the Workspace. With this key you can manage your entire instance, e.g. create or delete tenants. This is highly sensitive information and should be known within your organization. If you've lost the key, please submit a support ticket.

The Provisioning Key is provided via the value of a header called ProvisioningKey. An extra header is provided with every request X-Requested-With: XMLHttpRequest.

There is no GUI or a way to view the API from the Workspace. We describe the available endpoints and their data objects per resource type. Included in each endpoint is an example of the request. These examples assume Workspace 365 has the following settings:

Workspace 365 is hosted on https://yourworkspace365instance.url
The Provisioning Key is 00000000-0000-0000-0000-000000000000

Please note that this are example values. Please check your own values on your own instance.

Provisioning API Enabled

Only self-hosted partners need to check whether the Provisioning API is enabled. For our hosted platform, this is enabled by default.

This can be found in NDAW.WebApp.config with the name ProvisioningApiEnabled and should be set to either True of False, for example;

<setting name="ProvisioningApiEnabled" serializeAs="String">
    <value>TRUE</value>
</setting>

ProvisioningKey

Is used to indicate the value of the Provisioning Key which is used to authenticate to the API. The provisioning key is given when you start as a partner and should be known within your organization.

Self-hosted partners can find this in NDAW.WebApp.config with the name ProvisioningKey, this should be set to a non-empty string value, e.g.:

<setting name="ProvisioningKey" serializeAs="String">
       <value>00000000-0000-0000-0000-000000000000</value>
</setting>

Hosted partners who have lost their provisioning key can request a new one. We cannot provide or verify existing provisioning keys.

Preview APIs

Import/Export environment configuration

Things we currently export/import are;

Custom app images
Apps (both installed from the catalogue and custom ones)
Default workspace template
Shared tile groups
Shared spaces

NOTE: not all apps are exported/imported equally. Apps which have a relation to other configuration (e.g. Clientless RDP or Business App) will only be exported/imported partially. You will need to update them afterwards.

Endpoints

Environment

POST

/Provisioning/Environment/?version=2.0

Creates an Environment and user with administrator privileges with temporary password. Version 2

Name	Located in	Description	Required
Environment	Body	Environment to create	Yes

Schema:

{ EmailAddress:
 string (email)
Email address of the admin
EnvironmentName: string
Name of the environment
FirstName: string
First name of the admin
LastName: string
Last name of the admin
}

Code	Description	Schema
200	Name of the created Environment. This value can differ with the entered data since it is sanitized.	{ Id: string (in GUID format) Id of a newly created environment EnvironmentName: string Name of the created environment. TemporaryPassword: string Temporary password of created administrator }
400	Array of Validation Results	[ValidationResult]
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
500	Internal server error. This could be caused by passing an incorrect data object

Example

POST https://workspace365instance.url/Provisioning/Environment/?version=2.0 HTTP/1.1
Accept: application/json
Content-Length: 148
Content-Type: application/json
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest{
  "EnvironmentName": "{EnvironmentName}",
  "EmailAddress": "admin@example.com",
  "FirstName": "Admin",
  "LastName": "-"
}

PUT

/Provisioning/Environment/{EnvironmentName}/Activate

Activates the Environment

Name	Located in	Description	Required
EnvironmentName	Path	Name of the Environment	Yes

Schema

string

Responses

Code	Description	Schema
200	The Environment was set to active	string
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value	[ValidationResult]
404	The resource is not found
411	The header “Content-Length: 0” is missing
500	Internal server error. This could be caused by passing an incorrect data object

Example

PUT https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Activate/ HTTP/1.1
Accept: application/json
Content-Length: 0
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest

PUT

/Provisioning/Environment/{EnvironmentName}/Deactivate

Deactivates the Environment

Name	Located in	Description	Required
EnvironmentName	Path	Name of the Environment	Yes

Responses

Code	Description	Schema
200	The Environment was set to active	string
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value	[ValidationResult]
404	The resource is not found
411	The header “Content-Length: 0” is missing
500	Internal server error. This could be caused by passing an incorrect data object

Example

PUT https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Deactivate/ HTTP/1.1
Accept: application/json
Content-Length: 0
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest

DELETE

/Provisioning/Environment/{EnvironmentName}/

Deletes the Environment

Name	Located in	Description	Required
EnvironmentName	Path	Name of the Environment	Yes

Schema

string

Responses

Code	Description	Schema
200	The Environment was deleted	string
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value	[ValidationResult]
404	The resource is not found
500	Internal server error. This could be caused by passing an incorrect data object

Example

DELETE https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/ HTTP/1.1
Accept: application/json
ProvisioningKey: 00000000-0000-0000-0000-000000000000
Host: yourworkspace365instance.url
X-Requested-With: XMLHttpRequest

GET

/Provisioning/Environment/

Gets a list containing the environments

Responses

Code	Description	Schema
200	The environments	[ Environment { name: string The name of the environment isActive: boolean Whether the environment is active creationDate: date When the environment was created } ]
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
500	Internal server error. This could be caused by passing an incorrect data object

Example

GET https://workspace365instance.url/Provisioning/Environment/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

SSO

This endpoint can be used to reconfigure SSO if necessary. Refer to this article for instructions how to do this.

PUT

/Provisioning/{EnvironmentName}/SingleSignOnSettings/OAuth2/

Sets settings for OAuth2 authentication (not available when hosted on-premises)

Name	Located in	Description	Required	Schema
EnvironmentName	Path	Name of the environment	Yes	string
Settings	Body	OAuth2 settings to use	Yes	{ Authority: string (url) OAuth2 authority server url ClientID: string OAuth2 client IDKey: string OAuth2 key }

Responses

Code	Description	Schema
200	Success
400	Array of Validation Results	[ValidationResult]
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
404	The resource is not found
500	Internal server error. This could be caused by passing an incorrect data object

Example

PUT https://workspace365instance.url/Provisioning/example/SingleSignOnSettings/OAuth2/ HTTP/1.1 
Accept: application/json 
Content-Length: 184 
Content-Type: application/json 
Host: workspace365instance.url 
ProvisioningKey: 00000000-0000-0000-0000-000000000000 
X-Requested-With: XMLHttpRequest { 
  "Authority": "https://login.windows.net/company.onmicrosoft.com/", 
  "ClientId": "6ace5d40-604c-5b2a-102e-513d21132da8c", 
  "Key": "3e9jCju7tv7f9tz6BPjC711jupUUTF8BSqSAS7+asB=" 
}

Licensing

Self-hosted? You must be running at least v4.3 to use this API.

Version 3.5

The Licensing API V3.5 should be used while we are transitioning from the Simplify/Adapt/Boost licensing system to the Module licensing system (Hybrid/Engage/Unify). We also offer a Power BI dashboard for both APIs you can use for reporting.

GET

/Provisioning/{EnvironmentName}/Licensing/?version=3.5

Gets the Licenses summary, Module summary and customer information

Name	Located in	Description	Required	Schema
EnvironmentName	Path	Name of the Environment	Yes	string

Responses

Code	Description	Schema
200	The Licenses summary	{ summary: { guest: integer The number of active users with a guest license simplify: integer The number of active users with a simplify license adapt: integer The number of active users with an adapt license boost: integer The number of active users with a boost license }, moduleSummary: { regularUsers: { hybrid: integer The number of active non guest users with a hybrid module engage: integer The number of active non guest users with an engage module unify: integer The number of active non guest users with a unify module }, guestUsers: { hybrid: integer The number of active guest users with a hybrid module engage: integer The number of active guest users with an engage module unify: integer The number of active guest users with a unify module } }, customer: { name: string Name provided by a Customer referenceNumber: string Reference number provided by a Customer customerType: enum A number that maps to the Customer Type specified by a Customer 1: Business 2: Education 3: Non-Profit 4: Distributor industry: enum A number that maps to the industry Type specified by a Customer 1: Agriculture 2: Chemical 3: Construction 4: Defense 5: Education 6: Energy 7: Entertainment 8: Financial 9: Food 10: Governmental 11: Health Care 12: Hospitality 13: Information Technology 14: Manufacturing 15: Other 16: Software 17: Telecommunications 18: Transport UseNewBillingMethod: bool Specifies if the old or the new billing method must be used } }
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value.
404	Resource is not found.
500	Internal server error. This could be caused by passing an incorrect data object.

Example

GET https://portal.workspace365.net/Provisioning/example/Licensing/?version=3.5 HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Version 4.0

GET

/Provisioning/{EnvironmentName}/Licensing/?version=4.0

Gets the Module summary and customer information

Name	Located in	Description	Required	Schema
EnvironmentName	Path	Name of the Environment	Yes	string

Responses

Code	Description	Schema
200	The Licenses summary	{ moduleSummary: { regularUsers: { hybrid: integer The number of active non guest users with a hybrid module engage: integer The number of active non guest users with an engage module unify: integer The number of active non guest users with a unify module }, guestUsers: { hybrid: integer The number of active guest users with a hybrid module engage: integer The number of active guest users with an engage module unify: integer The number of active guest users with a unify module } }, customer: { name: string Name provided by a Customer referenceNumber: string Reference number provided by a Customer customerType: enum A number that maps to the Customer Type specified by a Customer 1: Business 2: Education 3: Non-Profit 4: Distributor industry: enum A number that maps to the industry Type specified by a Customer 1: Agriculture 2: Chemical 3: Construction 4: Defense 5: Education 6: Energy 7: Entertainment 8: Financial 9: Food 10: Governmental 11: Health Care 12: Hospitality 13: Information Technology 14: Manufacturing 15: Other 16: Software 17: Telecommunications 18: Transport } }
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value.
404	Resource is not found.
500	Internal server error. This could be caused by passing an incorrect data object.

Example

GET https://portal.workspace365.net/Provisioning/example/Licensing/?version=4.0 HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Template

GET

/Provisioning/Environment/{EnvironmentName}/Export/

Exports environment Workspace setup

The GET request retrieves the following from the environment:

Custom app images
Apps (both installed from the catalogue and custom ones)
- Not all apps are exported/imported equally. Apps that have a relation to other configurations (e.g. Clientless RDP or other integrations) will only be exported/imported partially. You will need to update these after importing.
Default workspace template
Shared tile groups
Shared spaces

Name	Located in	Description	Schema
EnvironmentName	Path	Name of the Environment	string

Responses

Code	Description	Schema
200	The exported environment configuration	EnvironmentConfiguration
400	Validation issue, check error response data format	ApiErrorResponse
401, 403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
404	The resource is not found
500	Internal server error. This could be caused by passing an incorrect data object

Example request:

GET https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Export/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "exportImportInfo": {
 "hostingInstanceId": "1cfaad2e-1b58-4dbe-5312-163bbd8a6bd8",
 "version": 1,
 "exportDateTime": "2019-10-30T15:25:58.9942878+01:00"
 },
 "appImages": [],
 "tileGroups": [
 {
 "name": "How To",
 "type": 2,
 "order": 1,
 "isNewTilesTarget": false,
 "tiles": [
 {
 "installedAppId": 1,
 "name": null,
 "appImage": null,
 "parameters": null,
 "position": {
 "column": 0,
 "row": 0
 },
 "dimension": {
 "columnSpan": 8,
 "rowSpan": 8
 },
 "color": null
 }
 ]
 },
 {
 "name": "To-Do",
 "type": 3,
 "order": 1,
 "isNewTilesTarget": false,
 "tiles": [
 {
 "installedAppId": 2,
 "name": null,
 "appImage": null,
 "parameters": null,
 "position": {
 "column": 0,
 "row": 0
 },
 "dimension": {
 "columnSpan": 8,
 "rowSpan": 8
 },
 "color": null
 }
 ]
 }
 ],
 "apps": [
 {
 "id": 1,
 "appId": 1,
 "type": null,
 "name": null,
 "parameters": null,
 "image": null,
 "color": null,
 "everyoneHasAccess": true,
 "maintenanceWindow": null,
 "conditionalAccessPolicy": null
 },
 {
 "id": 2,
 "appId": 2,
 "type": null,
 "name": null,
 "parameters": null,
 "image": null,
 "color": null,
 "everyoneHasAccess": true,
 "maintenanceWindow": null,
 "conditionalAccessPolicy": null
 }
 ]
}

PUT

/Provisioning/Environment/{EnvironmentName}/Import/

Imports an environment configuration

An environment configuration can only be imported to an environment that meets the following criteria:

Environment only has 1 user, the admin
No custom apps configured
No custom app icons added
No tile groups configured
No shared spaces configured, only the admin's personal space should exist

If any of these requirements are not met, the request will return an error 400 with the response "Environment is not empty".

Name	Located in	Description	Schema
EnvironmentName	Path	Name of the Environment	string
Configuration	Body	The configuration created during the export	EnvironmentConfiguration

Responses

Code	Description	Schema
200	Success
400	Validation issue, check error response data format	ValidationResult
401, 403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
404	The resource is not found
500	Internal server error. This could be caused by passing an incorrect data object

Example request:

PUT https://workspace365instance.url/Provisioning/Environment/{EnvironmentName}/Import/ HTTP/1.1
Accept: application/json
Content-Length: 23965
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Email (Exchange)

PUT

/Provisioning/{EnvironmentName}/ExchangeSettings/

Sets the exchange services settings

Please be aware that the PowerShellUrl is deprecated. This endpoint will remain working, but without ability of setting the PowerShellUrl. See this article for more info.

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Settings

Body

Exchange settings to use

Yes

{
 ServerType:
  enum The server type of the exchange server. -	Office365
 -	OnPremises
DefaultEwsUrl:
  string (url) Default EWS address used when performing 
 “Auto discover”.  When left out 
 this property is ignored}

Responses

Code	Description	Schema
200	Success
400	Array of Validation Results	[ValidationResult]
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
404	Resource is not found
500	Internal server error. This could be caused by passing an incorrect data object

Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/ExchangeSettings/ HTTP/1.1
Accept: application/json
Content-Length: 178
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest{
  "ServerType": "Office365",
  "DefaultEwsUrl": "https://outlook.office365.com/ews/exchange.asmx"
}

SharePoint

PUT

/Provisioning/{EnvironmentName}/SharePointSettings/

Sets the SharePoint services settings.

Please note you cannot change an existing environment's SharePoint URL with this API. The "DefaultUrl" value updates a field that is only used when logging in to a newly created environment for the first time as the admin who created the environment.

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Settings

Body

Exchange settings to use

Yes

{
  DefaultUrl:
    string (url)
  Default SharePoint address used when 
  performing “Auto discover”. 
  When left out this property is ignored
  
  AuthenticationType:
    enum
  The authentication type used when 
  connecting to SharePoint.
  -	Online
  -	ActiveDirectoryFederationServices
  -	OAuth2
}

Responses

Code	Description	Schema
200	Success
400	Array of Validation Results	[ValidationResult]
403	The Provisioning Key in the configuration is not defined or empty. The Provisioning API is not enabled in the configuration. The Provisioning Key in the header does not match the configured value
404	Resource is not found
500	Internal server error. This could be caused by passing an incorrect data object

Example

PUT https://workspace365instance.url/Provisioning/{EnvironmentName}/SharePointSettings/ HTTP/1.1
Accept: application/json
Content-Length: 72
Content-Type: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest{
  "DefaultUrl": "https://example.sharepoint.com",
  "AuthenticationType": "Online"
}

Health status

GET

/api/health

Gets the health check status

Health check status code

Status	Description
FAIL	The health check failed and the component is not available or did not response is in timely manner.
OK	The health check succeeded and the component is available.
NOT_APPLICABLE	The component is not used in this case and the health check was not executed.
TIMEOUT	The health check did not complete in a timely manner.

Responses

Code	Description	Schema
200	The health check summary	HealthCheckResult { overallStatus: string The combined result of all components. The status will be OK if all health checks performed were successful. components: list of ComponentHealthResult A list of the results of all the health checks on the individual components. productVersion: string The version of Workspace 365 software running. }
403	The Health API Key in the configuration is not defined or empty. The Health API is not enabled in the configuration. The Health API Key in the header does not match the configured value.
404	The resource is not found.
500	Internal server error.

Example

GET https://portal.workspace365.net/api/health HTTP/1.1 
Host: portal.workspace365.net 
HealthApiKey: 00000000-0000-0000-0000-000000000000

{   "overallStatus": "OK",   "components": [     {       "component": "Database",       "status": "OK",       "responseTime": "00:00:00.0092007"     },     {       "component": "Redis",       "status": "OK",       "responseTime": "00:00:00.0035770"     },     {       "component": "RabbitMq",       "status": "OK",       "responseTime": "00:00:00.0297460"     },     {       "component": "BlobStorage",       "status": "OK",       "responseTime": "00:00:00.0034293"     },     {       "component": "Elasticsearch",       "status": "OK",       "responseTime": "00:00:00.0783747"     }   ],   "productVersion": "4.7.0.732-rc" }

Introduction

The Workspace 365 Health API is intended to provide a quick overview of the state of the Workspace 365 components and the subservices we utilize. Is the database connection healthy? How long does it take to connect to it? And what about Redis or Blob Storage? The purpose is to automate and detect unhealthy service status or unhealthy dependencies.

This API uses a REST-ish interface meaning instead of calling Actions/Methods, you define the Action you want to perform on a resource via the HTTP METHOD GET and uses JSON as its data protocol.

Prerequisites

There are two prerequisites:

The API needs to be enabled in Workspace 365.
In order to access the Health API, a key needs to be provided with each request. The Health API Key is provided via the value of a header called HealthApiKey.

The Health API is located at /api/health (e.g. when Workspace 365 is hosted on 'https://portal.workspace365.net', the Health API is located at 'https://portal.workspace365.net/api/health').

There is no GUI or a way to view the API from the Workspace. We describe the available endpoint and the data objects per resource type. Included in the endpoint is an example of the request, assuming Workspace 365 has the following settings:

Workspace 365 is hosted on 'https://portal.workspace365.net'
The Health API Key is 00000000-0000-0000-0000-000000000000

Health API enabled

This is used to indicate whether the Health API is enabled.

This can be found in NDAW.WebApp.config with the name HealthApiEnabled. This should be set to either True or False, for example;

<setting name="HealthApiEnabled" serializeAs="String">
  <value>True</value> 
</setting>

Health API key

This is used to indicate the value of the Health API Key, which is needed to authenticate to the API.

This can be found in NDAW.WebApp.config with the name HealthApiKey. It should be set to a non-empty string value, e.g.:

<setting name="HealthApiKey" serializeAs="String"> 
  <value>00000000-0000-0000-0000-000000000000</value> 
</setting>

General Data objects

ComponentHealthResult {
    component:
     string
    The name of the component which was health-checked.

    status:
     string
    The result status of the health check performed for the component.

    responseTime:
     string
    The time elapsed while the health check was being performed, in the format hours: minutes : seconds (include fractional seconds).
}

RabbitMQ 'FAIL' status

Explanation:

RabbitMQ is a mandatory component of hosting the Document Move Service. RabbitMQ does not need to be hosted on the same machine (VM) as Workspace 365. These services communicate through a TCP connection, which is defined in the connection string configuration.

We always check the health status on each Workspace 365 web server individually. The status of the RabbitMQ service indicates if web server can connect to RabbitMQ. If the status of the RabbitMQ service is presented as a 'Fail', it might be that the check is done on a machine whilst the service runs on a different machine.

Solution:

On all web servers the RabbitMQ AddConnectionString must refer to the machine where the RabbitMQ service is running on, using "IP of machine" (IPOFMachine) with TCP port 5672.

AddConnectionString("RabbitMq", @"amqp://CreatedUser:CreatedPassword@IPOFMachine/Instancename");

In the parameter file also make sure AllowCrossSiteMove is set to "True":

AddTransform("AllowCrossSiteMove", @"True");

Provisioning script

API documentation

Provisioning example: Change SSO settings in Workspace 365

Step 1. Edit and zip the manifest.json file

Introduction to Workspace 365 APIs

Provisioning API (instance)

Introduction

Prerequisites

Provisioning API Enabled

ProvisioningKey

Preview APIs

Import/Export environment configuration

Endpoints

Environment

SSO

Licensing

Version 3.5

Version 4.0

Template

Email (Exchange)

SharePoint

Health status

Introduction

Prerequisites

Health API enabled

Health API key

General Data objects

RabbitMQ 'FAIL' status