Integration credentials API
- POST /{EnvironmentName}/IntegrationCredentialsApi/User/{Upn}/
- PUT /{EnvironmentName}/IntegrationCredentialsApi/{Id}/
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
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 |
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 Updates the credentialset |
||||||||||||||||||||
Parameters
|
||||||||||||||||||||
Responses
|
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