WhatsApp: 0623684723

Integration credentials API

Follow

Introduction

Workspace 365 Integration credentials API allows clients to manage Integration credentials records programmatically. The API is over HTTPS and uses JSON as the input and output data format.

In the documentation, values in curly braces e.g. {parameter} indicate placeholders for request parts to be replaced with actual values.

Prerequisites

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

  • Integration credentials API is enabled in the Workspace 365 environment

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

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 c67d8168-2efb-4737-95d7-b05ef335d098
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:

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.

 

Endpoints

POST /{EnvironmentName}/IntegrationCredentialsApi/User/{Upn}/

Description: Creates new Integration credentials for given user

Parameters

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://portal.workspace365.net/example/IntegrationCredentialsApi/User/userone@example.com/
HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: portal.workspace365.net
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098
 
{
  "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}/

Description

Activates the Environment

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://portal.workspace365.net/example/IntegrationCredentialsApi/8/ HTTP/1.1
Accept: application/json
Content-Length: 68
Content-Type: application/json
Host: portal.workspace365.net
Authorization: Workspace365 c67d8168-2efb-4737-95d7-b05ef335d098
 
{
  "username": "userone@example.com",
  "password": "qwerty_updated"
} 

Example response:

HTTP/1.1 200 OK
Content-Length: 0
Have more questions? Submit a request