Workspace 365 API (environment)

Created: June 28, 2021 11:36
Updated: September 07, 2021 10:21

Quick reference:

Settings -> Integrations -> API settings

Introduction
Prerequisites
Authentication
- Authentication response codes
API key
API's

Introduction

The Workspace 365 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.

In this article we discuss the different types of available Workspace API's and how to make use of them. First, an API key has to be created. 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.

Prerequisites

Environment administrator can configure the API on the API settings page. To be able to use the API, the following conditions should be met:

Make sure the API setting is configured and enabled in the settings.

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

It is strongly recommended not to use the API over non-https channels.

Authentication response codes

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

Code	Description
200	Response OK
400	Validation issue, check error response data format
401, 403	Authentication issue. One of the following applies: Authorization header is missing Authentication scheme is incorrect Token is invalid for the environment The API is not configured for the environment or the environment is inactive
500	Internal server error. This could be caused by passing an incorrect data object

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.

API key

API keys can be created in the Workspace settings > Integrations > API settings.

To create a new key, check the checkbox "Enable", 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.

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.

When a key is generated, it will no longer be stored in the Workspace. However, it is possible to regenerate API keys when for example when 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. It is also possible to temporarily disable a key.

API's

Activity Feed

Quick reference:

Settings -> Integrations -> API settings -> Activity feed API

Endpoints

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	Authentication issue
500	Internal server error

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": "[email protected]"
  },
  "Icon": {
      "Name": "Phone"
  },
  "Title": "Test activity",
  "Url": "https://workspace365instance.url",
  "Tag": "Proposals",
  "Color": {
      "Kind": "1",
      "Value": "#00ff00"
  },
  "Actions": [
     {
      "Kind": "1", 
      "Title": "Accept proposal",
      "Url": "https://workspace365instance.url/proposal/accept"
     }
  ]
}

Example response

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

{
   "id": 916,
   "user": {
       "id": 1,
       "upn": "[email protected]"
   }
}

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	Authentication issue
500	Internal server error

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": 0
 },
 "Data": {
    "Title": "test",
    "Url": "https://workspace365instance.url", 
    "Tag": "Proposals",     
    "Icon": {
      "Name": "Phone"
    },
    "Color": {
      "Kind": 1,
      "Value": "#00ff00"
    },
    "Actions": [
      {
        "Kind": 1
        "Title": "Accept Proposal",
        "Url": "https://workspace365instance.url/proposal/accept"
      }
    ]
  }
}

Example response

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

[
    {
        "id": 962,
        "user": {
            "id": 1,
            "upn": "[email protected]"
        }
    },
    …
]

Schemas

NONE

Activity schema

{
  "User": UserLookup,
  "Icon": Icon,
  "Title": "Test activity",
  "Url": "https://workspace365instance.url",
  "Tag": "Proposals",
  "Color": Color,
  "Actions": [
    Action
   ]
}

Property	Type	Optional/Required	Description
User	UserLookup	Required	Specifies the user for the activity.
Icon	Icon	Optional	Specifies the icon which is displayed in the activity. The default icon is displayed when no icon is specified.
Title	String	Required	The title which is displayed in the activity feed.
Url	String	Optional	A url to a page which shows more details about this activity. If a url is specified the activity feed shows ‘View details’.
Tag	String	Optional	A way to indicate what group the activity belongs to. If one is specified, the activity is grouped with other activities with the same tag. If none is specified, the activity will put in the "Other" group.
Color	Color Object	Optional	The default color is used when not specified.
Actions	Array of Action	Optional	Specifies a list of actions. The maximum number of actions is 2.

NONE

User schema

{
 "User": {
   "id": 1,
   "upn": "[email protected]"
   }
}

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.

NONE

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.

NONE

Color schema

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

Property	Type	Optional/Required	Description
Kind	Int	Required	Options are 1 (custom), 2 (primary), 3 (header).
Value	String	Required when Kind is 1	The Value property specifies a html color. The field is required when the Kind is 1.

NONE

Action schema

{
 "Kind": 1,
   "Title": "Accept proposal",
   "Url": “https://workspace365instance.url/propasal/accept"
}

Property

Type

Optional/Required

Description

Kind

Int

Required

This property determines which icon is shown next to the action title.

Options are: 1 (check), 2 (cancel), 3 (add), 4 (open), 5 (edit), 6 (manage), 7 (delete), 8 (forward), 9 (backward).

Title

String

Required

Specifies the title of the action. Maximum length is 32 characters.

Url

String

Required

The url the user is redirected to when invoking the action.

NONE

Batch Activity schema

{
  "Scope": Scope,
  "Data": ActivityWithoutUser
}

Property	Type	Optional/Required	Description
Scope	Scope	Required	Specifies the scope of users.
Data	ActivityWithoutUser	Required	Specifies the upn of the user. Note: id Specifies activity data.

NONE

Scope schema

{
  "Kind": 0,
  "Users": [
    UserLookup
],
  "Groups": [
    GroupLookup
  ]
}

Property	Type	Optional/Required	Description
Kind	Int	Required	Specifies the scope kind. Possible values: 0 (all users), 1 (users), 2 (groups).
Users	Array of UserLookup	Required when Kind is 1	his property is required when the scope kind is set to 1. The array should contain at least one user.
Groups	Array of GroupLookup	Required when Kind is 2	This property is required when the scope kind is set to 2. The array should contain at least one group.

NONE

UserLookup schema

{
  "id": 1,
  "upn": "[email protected]"
}

Property	Type	Optional/Required	Description
Id	Int	Required when upn is not specified	Specifies the user by Id. The Id or the upn should be specified. If both are specified, the Id is used.
Upn	String	Required when Id is not specified	Specifies the user by upn. The Id or the upn should be specified. If both are specified, the Id is used.

NONE

GroupLookup schema

{
  "id": 1,
  "name": "test-group"
}

Property	Type	Optional/Required	Description
Id	Int	Required when Name is not specified	Specifies the group by Id. The Id or the Name should be specified. If both are specified, the Id is used.
Name	String	Required when Id is not specified	Specifies the group by Name. The Id or the Name should be specified. If both are specified, the Id is used.

NONE

ActivityWithoutUser schema

{
  "Icon": Icon,
  "Title": "Test activity",
  "Url": "https://workspace365instance.url",
  "Color": Color,
  "Actions": [
    Action
  ]
}

Property	Type	Optional/Required	Description
Icon	Icon	Optional	Specifies the icon which is displayed in the activity. The default icon is displayed when no icon is specified.
Title	String	Required	The title which is displayed in the activity feed.
Url	String	Optional	A url to a page which shows more details about this activity. If a url is specified, the activity feed shows ‘View details’.
Tag	String	Optional	A way to indicate what group the activity belongs to. If one is specified, the activity is grouped with other activities with the same tag. If none is specified, the activity will put in the "Other" group.
Color	Color	Optional	The default color is used when not specified.
Actions	Array of Action	Optional	Specifies a list of actions. The maximum number of actions is 2.

Available user apps

Quick reference:

Settings -> Integrations -> API settings -> Available user apps

Endpoint

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, 403	Authentication failure
404	Validation issue	ApiErrorResponse
500	Internal server error

Example request

GET https://workspace365instance.url/example/api/users/[email protected]/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"
   }
  }
]

Mapping

NONE

App Kind Mapping

App Kind Integer Value	Color Kind Integer Value
0	Shortcut
1	Email
2	Document
15	Citrix App
20	Azure App
35	Local App
36	Windows Virtual desktop

NONE

Color Kind Mapping

Color Kind Integer Value	Color Kind Integer Value
1	Custom
2	Primary
3	Header

Announcements

Quick reference:

Settings -> Integrations -> API settings -> Announcements API

Endpoint

POST

/{EnvironmentName}/api/announcements

Creates new Announcement

Name	Located in	Description	Required	Schema
Environment name	Path	Name of the environment	Yes	string
Announcement	Body	Announcement to create	Yes	Announcement

Authentication response codes

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

Responses

Code	Description	Schema
200	The announcement is created	{ id: integer The id of the announcement which is created }
400	Validation issue	ApiErrorResponse
401, 403	Authentication failure
500	Internal server error

Error response

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.

Example request

POST https://workspace365instance.url/example/api/announcements HTTP/1.1
Accept: application/json
Content-Length: 9082
Content-Type: application/json
Host: workspace365instance.url
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

{
  "Title": "My announcement",
  "Description": "This is my <b>announcement</b>",
  "Media":
  {
     "MediaKind": 1,
     "Image":
    {
      "Filename": "Minions.jpg",
      "Uri": "data:image/jpeg;base64,/--base 64 image data here --"
   }
  },
  "Category":
  {
     "Id": 2
   },
   "ShowPopupDirectlyToUser": true,
   "AllowComments": true,
   "StartTime": "2021-04-15T00:00Z",
   "EndTime": "2021-04-18T00:00Z"
}

Example response

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

{
   "id": 916
}

Schemas

NONE

Announcement schema

{
"Title": "My announcement",
"Description": "This is my announcement",
"Media": Media,
"Category": Category,
"ShowPopupDirectlyToUser": true,
"AllowComments": true,
"StartTime": "2021-04-15T00:00Z",
"EndTime": "2021-04-18T00:00Z"
}

Property	Type	Optional/Required	Description
Title	String	Required	Specifies the title of the announcement.
Description	String	Optional	Specifies the description of the announcement.
Media	Media	Optional	Specifies the media to be added to the announcement.
Category	Category	Optional	Specifies the category of the announcement. If left empty, the announcement will be added to the "Uncategorized" section
ShowPopupDirectlyToUser	Boolean	Optional	Specifies whether to show the announcement as a popup. The default value is false.
AllowComments	Boolean	Optional	Specifies whether comments are enabled for the announcement. The default value is true.
StartTime	DateTimeOffset	Optional	Specifies the start date and time for the announcement.
EndTime	DateTimeOffset	Optional	Specifies the end date and time for the announcement.

NONE

Media schema

{
  "MediaKind": 1,
  "Image": Image
}

OR

{
  "MediaKind": 2,
   "VideoEmbedCode": "<iframe width=\"424\" height=\"238\" src=\"https://www.youtube.com/embed/1uDQQVnrDqI\" title=\"YouTube video player\"
frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\"
allowfullscreen></iframe>"
}

Property	Type	Optional/Required	Description
MediaKind	Integer	Optional	Specifies the type of media to be attached. Can be 0 (none), 1 (image) or 2 (video).
Image	Image	Required when MediaKind=1	Specifies the details of the image to be added. To be provided only if MediaKind = 1.
VideoEmbedCode	String	Required when MediaKind=2	Specifies the embed code of the video to be added. To be provided only if MediaKind = 2.

NONE

Image schema

{
  "Filename": "Minions.jpg",
  "Uri": "data:image/jpeg;base64,/--base 64 image data here --"
}

Property	Type	Optional/Required	Description
Filename	String	Required	Specifies the name of the image.
Uri	String	Required	Specifies the base 64 URI of the image.

NONE

Category schema

{
  "Id": 1,
  "Name": “Company"
}

Property	Type	Optional/Required	Description
Id	Integer	Optional*	Specifies the id of the category.
Name	String	Optional*	Specifies the name of the category.

* Only one of the options should be passed. If none are passed, then the announcement is added to “Uncategorized” by default.

App icons

Quick reference:

Settings -> Integrations -> API settings -> App icons API

This endpoint for images is an extension to the User available apps API (available from V3.30).

Endpoints

GET

/{EnvironmentName}/api/appicons/{Source}

Gets a list of all the global app icons

Name	Located in	Description	Required	Schema
Environment name	Path	Name of the environment	Yes	string
Source	Path	Source of the icon. Possible values are global or environment	Yes	String

Code	Description	Schema
200	The available icons are returned	[{ id: integer The app icon id kind: integer The icon kind name: string The name of the app icon } , ... ]
400	The requested app icon is not found, check error response data format	ApiErrorResponse
401, 403	Authentication failure
500	Internal server error

Example request

GET https://workspace365instance.url/example/api/appicons/global
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

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

[
  {
   "id": 1,
   "kind":0,
   "name":"Box"
 },
 {
   "id": 36,
   "kind":2,
   "name":"Computer Desktop"
  }
]

GET

/{EnvironmentName}/api/appicons/{Source}/{Id}

Gets information about a specific app icon

Name	Located in	Description	Required	Schema
Environment name	Path	Name of the environment	Yes	string
Source	Path	Source of the icon. Possible values are global or environment	Yes	String
Id	path	Id app icon	Yes	Integer

Code	Description	Schema
200	The app icon info is returned	{ id: integer The app icon id kind: integer The icon kind name: string The name of the app icon }
400	The requested app icon is not found, check error response data format	ApiErrorResponse
401, 403	Authentication failure
500	Internal server error

Example request

GET https://workspace365instance.url/example/api/appicons/global/36
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

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

{
  "id": 36,
  "kind":2,
  "name":"Computer Desktop"
}

GET

/{EnvironmentName}/api/appicons/{Source}/{Id}/content

Gets the content of a specific app icon

Name	Located in	Description	Required	Schema
Environment name	Path	Name of the environment	Yes	string
Source	Path	Source of the icon. Possible values are global or environment	Yes	String
Id	path	Id app icon	Yes	Integer

Code	Description	Schema
200	The available icons are returned	The content of the response contains the app icon data
400	The requested app icon is not found, check error response data format	ApiErrorResponse
401, 403	Authentication failure
500	Internal server error

Example request

GET https://workspace365instance.url/example/api/appicons/global/36/content
Authorization: Workspace365 00000000-0000-0000-0000-000000000000

Example response

HTTP/1.1 200 OK
Content-Type: image/svg+xml
Content-Length: 211

<svg fill="#fff" 
 xmlns="http://www.w3.org/2000/svg" viewBox="0 0 76 76">
 <path d="M6 57.126h64v6.742H6zm18.628-7.03h26.744v4.306H24.628zM10.444 15.99v30.588h55.112V15.99zm-4.026-3.858H69.58v37.666H6.418z"/>
</svg>

Icon kind

NONE

Icon kind

Icon Kind Integer Value	Meaning
0	Png image
1	Svg image
2	Svg image

Integration credentials

Quick reference:

Settings -> Integrations -> API Settings -> Integration credentials API

Endpoints

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	ApiErrorResponse
401, 403	Authentication issue
404	The user was not found

Example request

POST https://workspace365instance.url/{EnvironmentName}/IntegrationCredentialsApi/User/[email protected]/ HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: yourworkspace365instance.url
Authorization: Workspace365 4613e4c6-aa59-45d0-88c9-c99feddf3959
 
{
  "username": "[email protected]",
  "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	ApiErrorResponse
401, 403	Authentication issue
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": "[email protected]",
  "password": "qwerty_updated"
}

Example response

HTTP/1.1 200 OK
Content-Length: 0

ActiveDirectorySync

Quick reference:

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

Endpoints

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": "[email protected]",
"Email": "[email protected]",
"SecondaryEmail": "[email protected]",
"IsAdmin": "false",
"IsActive": "true",
"JobTitle": "",
"MobilePhone": ""

}

Responses

Code	Description	Schema
200	The user is created
400	Validation issue	ApiErrorResponse
401, 403	Authentication issue

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": "[email protected]",
"Email": "[email protected]",
"SecondaryEmail": "[email protected]",
"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	ApiErrorResponse
401, 403	Authentication issue

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	ApiErrorResponse
401, 403	Authentication issue

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	ApiErrorResponse
401, 403	Authentication issue

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	ApiErrorResponse
401, 403	Authentication issue

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	ApiErrorResponse
401, 403	Authentication issue

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	ApiErrorResponse
401, 403	Authentication issue

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	ApiErrorResponse
401, 403	Authentication issue

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

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

Was this article helpful?

Have more questions? Submit a request

Articles in this section

Workspace 365 API (environment)

Table of Contents

Introduction

Prerequisites

Authentication

Authentication response codes

Error responses

API key

API's

Activity Feed

Endpoints

Responses

Example request

Example response

Responses

Example request

Example response

Schemas

Available user apps

Endpoint

Example request

Example response

Mapping

Announcements

Endpoint

Authentication response codes

Responses

Error response

Example request

Example response

Schemas

App icons

Endpoints

Example request

Example response

Example request

Example response

Example request

Example response

Icon kind

Integration credentials

Endpoints

Responses

Example request

Example response

Responses

Example request

Example response

ActiveDirectorySync

Endpoints

Responses

Example request

Example response

Responses

Example request

Example response

Responses

Example request

Example response

Responses

Example request

Example response

Responses

Example request

Example response

Responses

Example request

Example response

Responses

Example request

Example response

Responses

Example request

Example response

Authentication

Related articles

Can't find what you're looking for?

Deal reg.

Get help