API Documentation

Created: July 16, 2020 09:58
Updated: March 19, 2021 15:33

Introduction
Prerequisites
Endpoints

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:

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

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

Provisioning API Enabled

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.

Click on Create key to generate a key.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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"
        }
    },
    …
]

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

Was this article helpful?

Have more questions? Submit a request

Articles in this section

API Documentation

Introduction

Prerequisites

Provisioning API Enabled

ProvisioningKey

API settings

Endpoints

Environment

Licensing

Template

Users

Email (Exchange)

SharePoint

Integration Credentials

Domain

ActiveDirectorySync

Prerequisites

Authentication

Authentication response codes

ActivityFeed API

Prerequisites

Authentication

Authentication response codes

ActivitySchema

User schema

Icon schema

Color schema

User available apps

Can't find what you're looking for?

Deal reg.

Get help

WhatsApp

Contact

Articles in this section

API Documentation

Introduction

Prerequisites

Provisioning API Enabled

ProvisioningKey

API settings

Endpoints

Environment

Licensing

Template

Users

Email (Exchange)

SharePoint

Integration Credentials

Domain

ActiveDirectorySync

Prerequisites

Authentication

Authentication response codes

ActivityFeed API

Prerequisites

Authentication

Authentication response codes

ActivitySchema

User schema

Icon schema

Color schema

User available apps

Related articles

Can't find what you're looking for?

Deal reg.

Get help

WhatsApp

Contact