Management API

Web Services / Integration API V6

Prerequisites

*** Prerequisites for the use of management web services ***

To obtain authentication access to the Trust and Sign web services, you must complete the account creation process with Namirial.

Management APIs are accessible with a specifically created or un-created Admin operator within the the operator administration page.

The basic URLs of the management APIs are as follows:

for the integration environment: https://integration-api.ekeynox.net. This environment is updated regularly and has the latest features;
for the pre-production environment: https://preprod-api.ekeynox.net. This environment is updated on the same date as production;
for the production environment: https://api.ekeynox.net;

The following chapters describe the JSON API. As the product evolves, we may add undocumented fields in the returns. You should therefore not be too restrictive on the payloads.

Please note that the names of the keys are case sensitive.

Authentication

Basic" authentication is used here; it follows the [RFC1945] standard (http://tools.ietf.org/html/rfc1945). An HTTP header named AUTHORIZATION must be added to requests. This header is of the form :

AUTHORIZATION = Basic base64(email:password)

The following code snippet can be used in Java to generate this header:

String header = "Basic " + Base64.getEncoder().encodeToString( ( email + ":" + password ).getBytes( StandardCharsets.UTF_8 ) );

For example, for a login "john123456" and a password "azerty" we get the following header is obtained:

AUTHORIZATION = Basic am9objEyMzQ1NjphemVydHk=

Error handling

If an error occurs during a request, a standard HTTP code is returned with an error JSON containing server-specific code Trust and Sign, an explanatory message and any invalid parameters.

For example:

{
  "error":{
    "message": "Server error",
    "code":1000
  }
}

Recovery of operators

** Request **

GET /contract/management/users?withInactive=false HTTP/1.1
Content-Type: application/json

Parameter	Description
withInactive`	(optional) Includes suppressed operators: true. Default value: false.

withInactive : (optional) Includes true suppressed operators. Default value: false.

** Back **

A JSON object containing the following information:

Path	Type	Description
`[].uuid`	`UUID`	Uuid
firstName`\|`String`	First Name
LastName	Last Name
[].email`\|`String`	Email
state`\| [ACTIVE, DELETE]`	Operator state
`[].authorizations`	`[ADMINISTRATION, VALIDATION, CLIENT_FILES_DOWNLOAD, CLIENT_FILES_TRANSFER, UPDATE_CLIENT_FILES]`	Authorizations
[].linkedToAllProducts`\|`Boolean`	Visibility of all Products
[].linkedToAllGroups`\|`Boolean`	Visibility of all Groups
ReportTypes`\| [ACTIVITY, EMAIL]`	List of activity report types
[].externalId`\|`String`	External identifier
ReportTypes is a list of all report types.

[
  {
    "uuid" : "28f4b088-fccf-4842-9319-09f4844c3d4a",
    "firstName" : "john",
    "lastName": "doe",
    "email" : "john.doe@namirial.com",
    "state" : "ACTIVE",
    "authorizations" : [ ],
    "reportTypes" : [ "ACTIVITY", "EMAIL" ],
    "linkedToAllProducts" : false,
    "linkedToAllGroups" : false,
    "externalId": "IdExternal"
  }
]

Creating an operator

** Request **

POST /contract/management/users/create HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "firstName" : "john",
  "lastName" : "doe",
  "authorizations" : [ "VALIDATION" ],
  "reportTypes" : [ "ACTIVITY", "EMAIL" ],
  "linkedToAllProducts" : false,
  "linkedToAllGroups" : false,
  "externalId": "IdExternal"
}

Path	Type	Description
FirstName	First Name
LastName	Lastname
email`\|`String`	Email
Authorizations`\| [ADMINISTRATION, VALIDATION, CLIENT_FILES_DOWNLOAD, CLIENT_FILES_TRANSFER, UPDATE_CLIENT_FILES]`	Authorizations
linkedToAllProducts`\|`Boolean`	Visibility of all Products
LinkedToAllGroups`\|`Boolean`	Visibility of all Groups
ExternalId	String	External Identifier
ReportTypes`\| [ACTIVITY, EMAIL]`	List of activity report types
reportTypes`\| [ACTIVITY, EMAIL]`	List of report types `[].reporting`	`Boolean`

** Back **

HTTP/1.1 204 No Content

Updating an operator

All fields are optional (except email). Only the fields present in the query are updated.

** Request **

PUT /contract/management/users/update HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "firstName" : "john",
  "lastName" : "doe",
  "authorizations" : [ "VALIDATION" ],
  "reportTypes" : [ "ACTIVITY", "EMAIL" ],
  "linkedToAllProducts" : false,
  "linkedToAllGroups" : false,
  "externalId": "IdExternal"
}

Path	Type	Description
FirstName	First Name
LastName	Lastname
`email`	`String`	Email
Authorizations`\| [ADMINISTRATION, VALIDATION, CLIENT_FILES_DOWNLOAD, CLIENT_FILES_TRANSFER, UPDATE_CLIENT_FILES]`	Authorizations
linkedToAllProducts`\|`Boolean`	Visibility of all Products
LinkedToAllGroups`\|`Boolean`	Visibility of all Groups
ExternalId	String	External Identifier
ReportTypes`\| [ACTIVITY, EMAIL]`	List of activity report types
reportTypes`\| [ACTIVITY, EMAIL]`	List of report types `[].reporting`	`Boolean`

** Back **

HTTP/1.1 204 No Content

Deleting an operator

DELETE /contract/management/users/delete HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com"
}

Path	Type	Description
email`\|`String`	Operator's email

** Back **

HTTP/1.1 204 No Content

Update of accessible products

PUT /contract/management/users/products/bind HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "productsPublicId" : [ "P1" ]
}

Path	Type	Description
email`\|`String`	Email
productsPublicId`\|`Array`	Public Product Id

** Back **

HTTP/1.1 204 No Content

Update of accessible groups

PUT /contract/management/users/groups/bind HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8

{
  "email" : "john.doe@namirial.com",
  "groupsLabel" : [ "DEFAULT" ]
}

Path	Type	Description
email`\|`String`	Email
groupsLabel`\|`class java.util.UUID`	Groups Label

** Back **

HTTP/1.1 204 No Content

Creation of operators by batch

** Request **

The content of the .csv file must comply with RFC4180 https://tools.ietf.org/html/rfc4180, have a header line with all the columns below.

POST /contract/management/users/create/csv HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name=csv; filename=file
Content-Type: text/plain

email,firstName,lastName,authorizations,reportTypes,linkedToAllProducts,linkedToAllGroups,productsPublicId,groupsLabel,externalId
john1.doe@namirial.com,john1,doe1,[ADMINISTRATION],[ACTIVITY|EMAIL],false,false,[],[DEFAULT],ext1
john2.doe@namirial.com,john2,doe2,[VALIDATION],[ACTIVITY],true,false,[P1|P2],[DEFAULT|G2],ext2
john3.d@@@namirial.com,john3,doe3,[],[],false,true,[P1],[],ext3

Part	Description
The .csv file

The authorizations, productsPublicId, groupsLabel columns are lists. The format of list items is as follows:

Prefix: [
Separator: |
Suffix: ]

** Back **

HTTP/1.1 200 OK
Content-Type: application/json

{
  "action" : "create",
  "usersSend" : 3,
  "usersSuccess" : 2,
  "usersError" : 1,
  "errors" : [ {
    "email" : "john3.d@@@namirial.com",
    "index" : 2,
    "reason" : "Invalid parameter 'email' format (Invalid email format)",
    "errorCode" : 1005
  } ]
}

Batch updating of operators

** Request **

The content of the .csv file must comply with RFC4180 https://tools.ietf.org/html/rfc4180, have a header line with all the columns below.

The email is the only mandatory column, all empty columns will not be modified.

POST /contract/management/users/update/csv HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name=csv; filename=file
Content-Type: text/plain

email,firstName,lastName,authorizations,reportTypes,linkedToAllProducts,linkedToAllGroups,productsPublicId,groupsLabel,externalId
john1.doe@namirial.com,john1,doe1,[VALIDATION],[ACTIVITY|EMAIL],false,false,[],[DEFAULT],ext1
john2.doe@namirial.com,john2,,,,,,,,
john3.d@@@namirial.com,john3,doe3,,[],false,true,[P1],[],ext3

Part	Description
The .csv file

The authorizations, productsPublicId, groupsLabel columns are lists. The format of list items is as follows:

Prefix: [
Separate: |
Suffix ]

** Back **

HTTP/1.1 200 OK

{
  "action" : "update",
  "usersSend" : 3,
  "usersSuccess" : 2,
  "usersError" : 1,
  "errors" : [ {
    "email" : "john3.d@@@namirial.com",
    "index" : 2,
    "reason" : "Invalid parameter 'email' format (Invalid email format)",
    "errorCode" : 1005
  } ]
}

Deleting operators by batch

** Request **

The content of the .csv file must comply with RFC4180 https://tools.ietf.org/html/rfc4180, have a header line with all the columns below.

DELETE /contract/management/users/delete/csv HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name=csv; filename=file
Content-Type: text/plain

email
john1.doe@namirial.com
john2.doe@namirial.com
john3.d@@@namirial.com

Part	Description
The .csv file

** Back **

HTTP/1.1 200 OK

{
  "action" : "delete",
  "usersSend" : 3,
  "usersSuccess" : 2,
  "usersError" : 1,
  "errors" : [ {
    "email" : "john3.d@@@namirial.com",
    "index" : 2,
    "reason" : "Invalid parameter 'email' format (Invalid email format)",
    "errorCode" : 1005
  } ]
}