Provisioning API (instance)

Table of Contents 


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:


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

Back to top

 

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>

Back to top

 

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.

Back to top

 

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

 

Back to top


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 ID
Key:
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=" 
} 

 

 

Back to top


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 s
pecified 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 s
pecified 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

Back to top


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

Back to top

 

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"
}

Back to top

 

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"
}

Back to top

 

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).
}

Back to top

 

RabbitMQ 'FAIL' status

healthcheck_api_fail.png

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");

Back to top