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.
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
Provisioning API Enabled
Is used to indicate whether the Provisioning API is enabled. This option is only available if you're hosting Workspace yourself.
This can be found in NDAW.Html.Front.config
with the name ProvisioningApiEnabled
and should be set to either TRUE
or FALSE
, e.g.:
<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.
This can be found in NDAW.Html.Front.config
with the name ProvisioningKey
and should be set to a non-empty string value, e.g.:
<setting name="ProvisioningKey" serializeAs="String"> <value>00000000-0000-0000-0000-000000000000</value> </setting>
Endpoints
Environment
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. |
{ |
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": "-"
}
UseEmptyEnvironment
or UseUserLicenses
is set to TRUE
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
Password:
string (password)
Password of the admin }
Responses
Code |
Description |
Schema |
---|---|---|
200 |
Name of the created Environment |
string |
400 |
Array of Validation Results |
[ValidationResult] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
500 |
Internal server error. This could be caused by passing an incorrect data object |
|
Example
POST https://workspace365instance.url/Provisioning/Environment/Validate/ 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", "Password": "qwerty", "FirstName": "Admin", "LastName": "-" }
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. |
[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
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. |
[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
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. |
[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
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The environments |
[ |
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
Licensing V3
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The Licenses summary |
{ |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
404 |
Resource is not found |
|
500 |
Internal server error. This could be caused by passing an incorrect data object |
Example
GET https://workspace365instance.url/Provisioning/{EnvironmentName}/Licensing/?version=3.0 HTTP/1.1 Accept: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest
Licensing V2 (deprecated)
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The Licenses summary |
{ guest: integer simplify: integer adapt: integer boost: integer } |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
404 |
Resource is not found |
|
500 |
Internal server error. This could be caused by passing an incorrect data object |
Example
GET https://workspace365instance.url/Provisioning/{EnvironmentName}/Licensing/?version=2.0 HTTP/1.1 Accept: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest
Template
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 |
|
|
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
}
]
}
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 |
|
|
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
Users
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
User |
Body |
User to create |
Yes |
{ EmailAddress: string (email) Email address of the user FirstName: string First name of the user IsAdministrator: boolean Whether the user is an Administrator LastName: string Last name of the user Password: string (password) Password of the user CreateInOffice365: boolean Whether the user should be created in Office 365 } |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The id of the created User |
integer |
400 |
Array of Validation Results |
[ValidationResult] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
404 |
Resource is not found |
|
500 |
Internal server error. This could be caused by passing an incorrect data object |
Example
POST https://workspace365instance.url/Provisioning/{EnvironmentName}/User/ HTTP/1.1 Accept: application/json Content-Length: 176 Content-Type: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest { "EmailAddress": "userone@example.com", "Password": "qwerty", "FirstName": "User", "LastName": "One", "IsAdministrator": false, "CreateInOffice365": false }
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
User |
Body |
User to create |
Yes |
{ EmailAddress: string (email) Email address of the user FirstName: string First name of the user IsAdministrator: boolean Whether the user is an Administrator LastName: string Last name of the user Password: string (password) Password of the user CreateInOffice365: boolean Whether the user should be created in Office 365 } |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The id of the created User |
integer |
400 |
Array of Validation Results |
[ValidationResult] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
404 |
Resource is not found |
|
500 |
Internal server error. This could be caused by passing an incorrect data object |
Example
POST https://workspace365instance.url/Provisioning/{EnvironmentName}/User/ HTTP/1.1 Accept: application/json Content-Length: 176 Content-Type: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest { "EmailAddress": "userone@example.com", "Password": "qwerty", "FirstName": "User", "LastName": "One", "IsAdministrator": false, "CreateInOffice365": false }
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
EmailAddress |
Path |
Email address of the User |
Yes |
string |
User |
Body |
User to create |
Yes |
{ EmailAddress: string (email) Email address of the user FirstName: string First name of the user IsAdministrator: boolean Whether the user is an Administrator LastName: string Last name of the user Password: string (password) Password of the user } |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The User was updated |
|
400 |
Array of Validation Results |
[ValidationResult] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
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/{EnvironmentName}/User/userone@example.com/ HTTP/1.1 Accept: application/json Content-Length: 145 Content-Type: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest { "EmailAddress": "userone@example.com", "Password": "qwert", "FirstName": "User", "LastName": "Once", "IsAdministrator": false }
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
EmailAddress |
Path |
Email address of the User |
Yes |
string |
User |
Body |
User to update |
Yes |
{ EmailAddress: string (email) Email address of the user FirstName: string First name of the user IsAdministrator: boolean Whether the user is an Administrator LastName: string Last name of the user Password: string (password) Password of the user } |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The entered User is valid for update |
|
400 |
Array of Validation Results |
[ValidationResult] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
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/{EnvironmentName}/User/userone@example.com/ HTTP/1.1 Accept: application/json Content-Length: 145 Content-Type: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest { "EmailAddress": "userone@example.com", "Password": "qwert", "FirstName": "User", "LastName": "Once", "IsAdministrator": false }
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
EmailAddress |
Path |
Email address of the User |
Yes |
string |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The user was set to Active |
|
400 |
Array of Validation Results |
[ValidationResult] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
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/{EnvironmentName}/User/userone@example.com/Activate/ HTTP/1.1 Accept: application/json Content-Length: 0 Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
EmailAddress |
Path |
Email address of the User |
Yes |
string |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The user was set to Deactivate |
|
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
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/{EnvironmentName}/User/userone@example.com/Deactivate/ HTTP/1.1 Accept: application/json Content-Length: 0 Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
EmailAddress |
Path |
Email address of the User |
Yes |
string |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The user was Deleted |
|
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
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/{EnvironmentName}/User/userone@example.com/ HTTP/1.1 Accept: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest
Email (Exchange)
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
Settings | Body | Exchange settings to use | Yes |
{ PowerShellUrl: string (url) Url of the Exchange server (the EWS endpoint) 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. |
|
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 { "PowerShellUrl": "https://outlook.office365.com/powershell-liveid/", "ServerType": "Office365", "DefaultEwsUrl": "https://outlook.office365.com/ews/exchange.asmx" }
SharePoint
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. |
|
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" }
Domain
Name |
Located in |
Description |
Required |
Schema |
---|---|---|---|---|
EnvironmentName |
Path |
Name of the Environment |
Yes |
string |
Responses
Code |
Description |
Schema |
---|---|---|
200 |
The domains registered with Office 365 |
[ Domain { isDefault: boolean Whether it is the default domain name: string The domain name } ] |
403 |
The Provisioning Key in the configuration is not defined or empty. |
|
404 |
Resource is not found |
|
500 |
Internal server error. This could be caused by passing an incorrect data object |
Example
GET https://workspace365instance.url/Provisioning/{EnvironmentName}/Domain/ HTTP/1.1 Accept: application/json Host: yourworkspace365instance.url ProvisioningKey: 00000000-0000-0000-0000-000000000000 X-Requested-With: XMLHttpRequest