Follow

API Documentation

 
  1. Introduction
  2. Prerequisites
    1. Enable API
    2. ProvisioningKey
    3. API settings
  3. Endpoints
    1. Environment
    2. Licensing
    3. Template
    4. Users
    5. Email (Exchange)
    6. SharePoint
    7. Integration Credentials
    8. Domain
    9. ActiveDirectorySync
    10. ActivityFeed
    11. Business Apps (deprecated)
    12. User available apps

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 The API needs to be enabled in Workspace 365. Some API's can be enabled via the GUI but most only via the config file on instance level.

 

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:


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

Back to top

 

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 TRUEor 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>
Looking for the ProvisioningsKey and you're hosted? Please raise a ProvisioningsKey ticket and we'll help you out!

API settings

Quick reference:
Settings -> Integrations -> API settings

Go to the workspace settings and navigate to Integrations > API settings. 

Instead of one API key for one functionality (e.g. integrations or activities), you can create multiple keys. With this feature you can receive activities from different parties - a unique key for each party. This contributes to security.

It is possible to temporarily disable a key. 

To create a new key, check the checkbox Enable and fill in a name (e.g. "API key for Yammer integration") and select the scope of the key. 

mceclip0.png

Click on Create key to generate a key. 

blobid1.png

Important: when a key is generated, it will no longer be stored in the workspace. When the dialogue as shown above is closed, the user cannot retrieve the key from the workspace anymore. Make sure you store this key somewhere secure.

However, it is possible to regenerate API keys when for example the key has been compromised or forgotten. When regenerating the key, the old key no longer works as you will be prompted with the dialogue as shown below.

blobid2.png

Editing the key will only give you the option to change the name, change the scope of the key or disable it. 

Back to top

 

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

 

POST
/Provisioning/Environment/Validate
Validates if the given Environment is valid for creating an Environment with Administrator user

 

Is NOT available when 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.
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/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": "-" }

 

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

 

Licensing

GET
/Provisioning/{EnvironmentName}/Licensing/?version=2.0
Gets the User Licenses summary

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.
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://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

Back to top

 

Template

GET
/Provisioning/Environment/{EnvironmentName}/Export/
Exports environment workspace setup (installed apps, tile groups, etc)
If you want to import a template, no existing template should be present. So this is only applicable for new, not configured environments. Import and Export is only possible to the same hosting instance.

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
If you want to import a template, no existing template should be present. So this is only applicable for new, not configured environments. Import and Export is only possible to the same hosting instance.

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

 

Users

POST
/Provisioning/{EnvironmentName}/User/
Creates a User

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

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
}
POST
/Provisioning/{EnvironmentName}/User/Validate/
Validates if the given User is valid for creating

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

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
}
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/
Updates a User

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.
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/{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
}
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/Validate/
Validates if the given User is valid for update

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.
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/{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
}
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/Activate/
Activates the User

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

 

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
PUT
/Provisioning/{EnvironmentName}/User/{EmailAddress}/Deactivate/
Deactivates the User

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

 

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
DELETE
/Provisioning/{EnvironmentName}/User/{EmailAddress}/
Deletes the User

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

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

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
{
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.
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

{
  "PowerShellUrl": "https://outlook.office365.com/powershell-liveid/",
  "ServerType": "Office365",
  "DefaultEwsUrl": "https://outlook.office365.com/ews/exchange.asmx"
}

Back to top

 

SharePoint

PUT
/Provisioning/{EnvironmentName}/SharePointSettings/
Sets the SharePoint services settings

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string
Settings Body SharePoint 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
  -	OnPremisesMixed
  -	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

 

Integration Credentials

Quick reference:
Settings -> Integrations -> API Settings -> Integration credentials API
Each request to the API should be authenticated with the token generated on the API settings page. Each environment requires its own token. For authentication use the standard HTTP Authorization header with Workspace365 authentication scheme and token as credentials:

Authorization: Workspace365 {token}

E.g. Authorization:

Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
POST
/{EnvironmentName}/IntegrationCredentialsApi/User/{Upn}/
Creates new Integration credentials for given user

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Upn

Path

User principal name of the user to create the Integration credentials for

Yes

string

Integration credentials

Body

Integration credentials to create

Yes

{
        
        username:
        string (email)
        Username of the Integration credentials
        password: string
        Password of the Integration credentials 
        
}

Responses

Code

Description

Schema

200

The Integration credentials were created

{
        id:
            integer 
        The id of the Integration credentials which were created
}

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

404

The user was not found

 

Example request:

POST https://workspace365instance.url/{EnvironmentName}/IntegrationCredentialsApi/User/userone@example.com/ HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
 
{
  "username": "userone@example.com",
  "password": "qwerty"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 8
 
{"id":8}
PUT
/{EnvironmentName}/IntegrationCredentialsApi/{Id}/
Updates the credentialset

Parameters

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string 

 

Id

Path

Id of the Integration credentials to update

Yes

integer

Integration credentials

Body

New properties of the Integration credentials

Yes

{
        username:
         string (email)
        Username of the Integration credentials
        password:
         string
        Password of the Integration credentials
}

 

Responses

Code

Description

Schema

200

The Integration credentials were updated

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

404

The Integration credentials were not found

 


Example request:

PUT https://workspace365instance.url/{EnvironmentName}/IntegrationCredentialsApi/8/ HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
 
{
  "username": "userone@example.com",
  "password": "qwerty_updated"
} 

Example response:

HTTP/1.1 200 OK
Content-Length: 0

Back to top

 

Domain

GET
/Provisioning/{EnvironmentName}/Domain/
Gets a list containing the domains registered with Office 365

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.
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://workspace365instance.url/Provisioning/{EnvironmentName}/Domain/ HTTP/1.1
Accept: application/json
Host: yourworkspace365instance.url
ProvisioningKey: 00000000-0000-0000-0000-000000000000
X-Requested-With: XMLHttpRequest

Back to top

 

ActiveDirectorySync

Quick reference:
Settings -> Users & groups -> Active Directory -> Sync API authentication token

Prerequisites

To be able to use the API, the following conditions should be met:

  • Active Directory Sync token is enabled in the Workspace 365 environment

The environment administrator can get the API token on the Active Directory settings page, and the authentication token will be generated.

Authentication

Each request to the API should be authenticated with the token generated on the Active Directory settings page. Each environment requires its own token.

For authentication use the standard HTTP Authorization header with "Basic" authentication scheme and token base64 encoded as credentials:

Authorization: Basic base64({token}:)

E.g. Authorization:

Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==
Make sure to use the Sync API authentication token and encode this to Base64 formate e.g. here. Keep in mind that you need to encode the token including the semicolomn :. For example:
Token: 4613e4c6-aa59-45d0-88c9-c99feddf3959
Text to encode: 4613e4c6-aa59-45d0-88c9-c99feddf3959:
Result: NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Authentication response codes

The API responds with the following HTTP status codes in case of authentication failure:

Responses

Code

Description

Schema

401

One of the following applies:

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

403

The Integration credentials API is not enabled for the environment

 

Error responses

When an action cannot be performed because of incorrect input data, the response will be an HTTP status code 400 containing an JSON object having a “globalError” and “fieldErrors” property.

Property “globalError” will be set to a non-null object in case of a validation error which is not connected to a single specific field. It is a JSON object with a “message” property containing potentially human-readable error description.

Property “fieldErrors” will be set if some field values failed the validation. For every such a field there would be a property named the same as in the input, containing a JSON object with a “message” property containing potentially human-readable error description.

Human readable messages can be given in one of the languages supported by Workspace 365 if the request contains a corresponding Accept-Language header.

 

PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectId}/
Creates new user

Name

Located in

Description

Schema

EnvironmentName

Path

Name of the Environment

string

ObjectId

Path

ObjectId of the user

Guid

User Info

Body

User Info to create

{

"FirstName": "Sarah",
"LastName": "de Vries",
"UserPrincipalName": "sarah@w365support.onmicrosoft.com",
"Email": "sarah@365support.onmicrosoft.com",
"SecondaryEmail": "anthony@w365support.onmicrosoft.com",
"IsAdmin": "false",
"IsActive": "true",
"JobTitle": "",
"MobilePhone": ""

}

Responses

Code

Description

Schema

200

The user is created

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==
         
        {

"FirstName": "Sarah",
"LastName": "de Vries",
"UserPrincipalName": "sarah@w365support.onmicrosoft.com",
"Email": "sarah@365support.onmicrosoft.com",
"SecondaryEmail": "anthony@w365support.onmicrosoft.com",
"IsAdmin": "false",
"IsActive": "true",
"JobTitle": "",
"MobilePhone": ""

}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectId}/
Deletes the given user

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

ObjectId

Path

ObjectId of the user

Yes

Guid

Responses

Code

Description

Schema

200

The user is deleted

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response:

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectId}/
Creates new group

Name

Located in

Description

Schema

EnvironmentName

Path

Name of the Environment

string

ObjectId

Path

ObjectId of the group

Guid

Group info

Body

Group info to create

{

"Name": "Finance",
"Description": "Everyone from Finance"

}

Responses

Code

Description

Schema

200

The group is created

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/9acasd74-0599-45ac-b0fe-a0aa0b9a00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

{

"Name": "Finance",
"Description": "Everyone from Finance"

}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectId}/
Deletes the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

ObjectId

Path

ObjectId of the group

Yes

Guid

Responses

Code

Description

Schema

200

The group is deleted

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response:

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectID}/Users/{ObjectID}
Put user in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Group ObjectId

Path

ObjectId of the group

Yes

Guid
User ObjectId  Path ObjectId of the user  Yes
Guid

Responses

Code

Description

Schema

200

The membership is created

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response:

HTTP/1.1 200 OK
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/{ObjectID}/Users/{ObjectID}
Delete user in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Group ObjectId

Path

ObjectId of the group

Yes

Guid
User ObjectId  Path ObjectId of the user  Yes
Guid

Responses

Code

Description

Schema

200

The membership is deleted

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Users/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response:

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/{ObjectID}/Groups/{ObjectID}
Put group in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Target Group ObjectId

Path

ObjectId of the target group

Yes

Guid
Group ObjectId Path ObjectId of the group  Yes
Guid

Responses

Code

Description

Schema

200

The membership is created

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

PUT https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/ HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response:

HTTP/1.1 200 OK
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/{ObjectID}/Groups/{ObjectID}
Delete group in the given group

Name

Located

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Target Group ObjectId

Path

ObjectId of the target group

Yes

Guid
Group ObjectId  Path ObjectId of the group  Yes
Guid

Responses

Code

Description

Schema

200

The membership is deleted

 

400

Validation issue, check error response data format

ApiErrorResponse

401, 403

Authentication issue, check potential reasons

 

Example request:

DELETE https://workspace365instance.url/{EnvironmentName}/ActiveDirectorySyncAPI/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a/Groups/4dcvcd74-9103-45ac-b0fe-a0aa0b1d00a HTTP/1.1
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Basic NDYxM2U0YzYtYWE1OS00NWQwLTg4YzktYzk5ZmVkZGYzOTU5Og==

Example response:

HTTP/1.1 200 OK
PUT
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture
Put the profile picture of the user
Note: User Profile Picture is not tested/documented yet.

Multipart form

PUT https://{WorkspaceUrl}/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture
DELETE
/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture
Delete the profile picture of the user
Note: User Profile Picture is not tested/documented yet.

Multipart form

DELETE https://{WorkspaceUrl}/{EnvironmentName}/ActiveDirectorySyncAPI/Users/{ObjectID}/ProfilePicture

Back to top

 

ActivityFeed API

Quick reference:
Settings -> Integrations -> API settings -> Activity feed API

Prerequisites

To be able to use the API, the following conditions should be met:

  • At least one Activity Feed API setting is configured in Workspace 365 environment

Environment administrator can configure the API on the API settings page.

Authentication

Each request to the API should be authenticated with the token generated on the API settings page. Each environment requires its own token.

For authentication use the standard HTTP Authorization header with "Workspace365" authentication scheme and token as credentials:

Authorization: Workspace365 {token}

E.g. Authorization:

Workspace365 00000000-0000-0000-0000-000000000000

Authentication response codes

The API responds with the following HTTP status codes in case of authentication failure:

Responses

Code

Description

Schema

401

One of the following applies:

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

403

The Activity Feed API is not configured for the environment, or the environment is inactive.

 

Error responses

When an action cannot be performed because of incorrect input data, the response will be an HTTP status code 400 containing an JSON object having a “globalError” and “fieldErrors” property.

Property “globalError” will be set to a non-null object in case of a validation error which is not connected to a single specific field. It is a JSON object with a “message” property containing potentially human-readable error description.

Property “fieldErrors” will be set if some field values failed the validation. For every such a field there would be a property named the same as in the input, containing a JSON object with a “message” property containing potentially human-readable error description.

Human readable messages can be given in one of the languages supported by Workspace 365 if the request contains a corresponding Accept-Language header.

ActivitySchema

{
"User": {
  "upn": "userone@example.com",
  "id": 1"
},
"Icon": {
  "Name": "my icon"
},
"Title": "Test activity",
"Url": "https://workspace365.net",
"Color": {
  "Kind": "Custom",
  "Value": "#00ff00"
  }
}

Property

Type

Optional/Required

Description

User

User

Required

Specifies the user for the activity. Upn or id should be supplied.

Icon

Icon

Optional

Specifies the icon which is displayed in the activity. The default icon is displayed when no icon is specified. We make use of the icon name which can be found in the app store.

Title

String

Required

The title which is displayed in the activity feed.

Url

String

Required

A url to a page which shows more details about this activity. If a url is specified the activity feed shows ‘View details’.

Color

Color Object

Optional

The default color is used when not specified. Options are Primary, Header and Custom.

User schema

{
  "User": {
  "id": 1,
  "upn": "userone@example.com"
}

Property

Type

Optional/Required

Description

id

Integer

Optional

Specifies the id of the user. Note: id or upn should be specified.

upn

String

Optional

Specifies the upn of the user. Note: id or upn should be specified.

Icon schema

{
  "Name": "my icon"
}

Property

Type

Optional/Required

Description

Name

String

Optional

Specifies the name of the icon. The default icon is displayed when no name is specified.

Color schema

{
  "Kind": "Custom",
  "Value": "#00ff00"
}

Property

Type

Optional/Required

Description

Kind

String

Required

Options are Primary, Header and Custom.

Value

String

Required when Kind is Custom

The Value property specifies a html color. The field is required when the Kind is Custom.

 

POST
/{EnvironmentName}/api/activities
Creates new Activity for given user

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Activity

Body

Activity to create

Yes

Activity

 

Responses

Code

Description

Schema

200

The Activity is created

{
id:
  integer 
The id of the activity which is created
user: {
  id:
  integer 
  The id of the user
  upn:
  string 
  The upn of the activity which is created

Note: Either id or upn should be specified (not both)
  }
}

400

Array of Validation Results

ApiErrorResponse

401, 403

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

500

Internal server error. This could be caused by passing an incorrect data object.

 


Example request

POST https://workspace365instance.url/{EnvironmentName}/api/activities HTTP/1.1
Accept: application/json
Content-Length: 228
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 00000000-0000-0000-0000-000000000000
  
{
  "User": {
      "Upn": "userone@example.com"
  },
  "Icon": {
      "Name": "Phone"
  },
  "Title": "Test activity",
  "Url": "https://workspace365.net",
  "Color": {
      "Kind": "Custom",
      "Value": "#00ff00"
  }
}


Example response

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

{
    "id": 916,
    "user": {
        "id": 1,
        "upn": "userone@example.com"
    }
}
POST
/{EnvironmentName}/api/activities-batch
Creates new activity for a certain scope of users

Name

Located in

Description

Required

Schema

EnvironmentName

Path

Name of the Environment

Yes

string

Batch Activity

Body

Batch Activity to create

Yes

Batch Activity

 

Responses

Code

Description

Schema

200

The Activity is created

[{
  id:
  integer 
  The id of the activity which is created
  user: {
      id:
    integer 
    The id of the user
    upn:
    string 
    The upn of the activity which is created
  }
}
,
  …
]

400

Array of Validation Results

ApiErrorResponse

401, 403

Authorization header is missing
Authentication scheme is incorrect
Token is invalid for the environment

 

500

Internal server error. This could be caused by passing an incorrect data object.

 


Example request

POST https://workspace365instance.url/{EnvironmentName}/api/activities-batch HTTP/1.1
Accept: application/json
Content-Length: 258
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

{
  "Scope": {
      "Kind": "AllUsers"
  },
  "Data": {
      "Title": "Workspace 365 Website Activity",
      "Url": "https://workspace365.net",      
      "Icon": {
          "Name": "Phone"
      },
      "Color": {
          "Kind": "Custom",
          "Value": "#00ff00"
      }
  }
}


Example response

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

[
    {
        "id": 962,
        "user": {
            "id": 1,
            "upn": "userone@example.com"
        }
    },
    …
]

Back to top

 

User available apps

GET
/{EnvironmentName}/api/users/{upn}/apps
Gets all the available apps for the given user upn

Name

Located in

Description

Required

Schema

Environment name

Path

Name of the environment

Yes

string

UPN

Path

User upn

Yes

string

 

 

Code

Description

Schema

200

The available apps are returned 

[{ 

  appId: 
   integer  
   The app id 

  type: 
   integer  
   The app type 

  icon: { 
      name: 
    string  
    The name of the icon 
    } 

  appName: 
   string  
   The name of the app 

  url: 
   string  
   The URL of the app 
   NOTE: The URL can be null 

  color: { 
      kind: 
    integer  
    The type of color used  

   value: 
    string  
    The hex value for the color. 
    NOTE: This field is present only     
    when the color kind is  
    custom.(Kind=1) 

    } 
} 
, 
  … 
] 
              

401

Authentication failure:
- authorization header is missing 

- authentication scheme is incorrect

- token is invalid for the environment 

 

403

Authentication failure:

The Activity Feed API is not configured for the environment, or the environment is inactive. 

 

404

Validation issue, check error response data format.

When an action cannot be performed because of incorrect input data, the response will be an HTTP status code 404 containing an JSON object having a globalError and fieldErrors property. 

Property “globalError” will be set to a non-null object in case of a validation error which is not connected to a single specific field. It is a JSON object with a “message” property containing potentially human-readable error description. 

Property “fieldErrors” is never set in the case of Activity Feed API. 

Human readable messages can be given in one of the languages supported by Workspace 365 if the request contains a corresponding Accept-Language header. 

ApiErrorResponse

500

Internal server error. This could be caused by passing an incorrect data object

 

Example request

GET https://workspace365instance.url/example/api/users/userone@example.com/apps
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

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

[
{ 
"appId": 34,
"type": 21,
"icon": {
"name": "Computer Desktop"
},
"appName": "TestClientlessRDP",
"url": "https://workspace365instance.url /example/AppLink/Go/00000000-0000-0000-0000-000000000000",
"color": {
"kind": 1,
"value": "#ff0000"
}

}
]

Back to top