Milieu API Overview

Modified on Wed, 13 Mar, 2024 at 2:17 PM

TABLE OF CONTENTS

Authorization
API Configuration
API Integration

Authorization

Authorization for all privileged endpoints should be performed via the Authorization Bearer header.

There are two supported authorization modes:

1. JWT - requires a valid Authorization header & public key

2. JWT with payload hash - requires a valid Authorization header, public key & payload bodyHash

Authorization Header:

The Authorization header name (e.g. X-Authorization) that you define is used to read the bearer token from.

Example:

Your authorization header should look like this:

X-Authorization: Bearer <token>

It is preferred that the JWT utilizes the ES256 JWS configuration mode and be signed with the following specifications:

HEADER: ALGORITHM & TOKEN TYPE

{

"alg": "ES256",

"typ": "JWT"

}

Generation of Public Key:

The SSH public key is used to verify the authenticity of the tokens. Follow the steps below to generate a public key in the supported PKCS8 format with ECDSA encryption algorithm.

On you preferred command line interface, type the following command to generate a new SSH key-pair:

openssl ecparam -name prime256v1 -genkey -noout -out private_key.pem

This command will generate a private key named private_key.pem

Convert the private key into PKCS8 format

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private_key.pem -out private_key_pkcs8.pem

Once the private key is generated, run the following command to extract the public key:

openssl ec -in private_key_pkcs8.pem -pubout -out public_key.pem

This command will generate a public key named public_key.pem

When you run cat public_key.pem you should be able to see the public key in the following format

-----BEGIN PUBLIC KEY-----

MFkwWeYHKoZIzj0CAQYIKoZIzj0DAQcD06AE60X2Gpb8NeXSYfdDFEhSHcuDL0NN

Sm+kn8O0f8DU9VeqNBk89+cgUuHuoLD0bpR5K1usTqXrJT84E3mq7WZf4yw==

-----END PUBLIC KEY-----

you can then copy the key with cat public_key.pem | pbcopy

Payload Body Hash:

It is recommended that the JWT include a claim within the payload presenting a value equal to the SHA256 hash of the submitted request body. This claim property is designed to ensure that the request body has not been tampered with from the point of origin.

The Payload Body Hash property (e.g. bodyHash) that you define is used to read the payload body hash from.

Example:

PAYLOAD:
{
"iat": <validity timestamp>,
"bodyHash": <sha256 hash of request body>
}

API Configuration

This section allows configuration of the API for external system (e.g. INFORM) to insert authorized respondent IDs into the eSurveys 2.0 (Milieu Canvas 2.0) system for a given survey endpoint.

The API configuration consists of 3 sections:

1. Authorization

Defines the authorization methods used for the API, refer to Authorization section

2. Respondent ID Definition

To facilitate respondent upsert and delete API through the provided baseURL

The baseURL is dependent on the survey link address and includes a unique identifier for a survey distribution group
POST: https://survey.mili.eu/<unique_identifier_for_survey_distribution>/respondents
GET: https://survey.mili.eu/<unique_identifier_for_survey_distribution>

The request body should be in JSON format contain the following data:

insert

Array of respondent IDs to be inserted.

Respondent IDs which already exist will not be modified.

delete

Array of respondent IDs to be deleted.

Sample Request:

POST https://survey.mili.eu/tSqYnPRwnxj495fl2aK5vcMgAHLApnCLW12MfOZZ/respondents HTTP/1.1

Host: survey.mili.eu

Content-Type: application/json

Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1MTYyMzkwMjIsImhhc2giOiJiYzZiYWU1MzQ5OGE3ZGJkZmFlMGJkNWFjNzViMzc3MzdiMmM1MmU4

MDhiYWExNjU3MDU1ZDVhNjMzNzQ2MDRhIn0._zYRyq4T4KpSLTvrt1SAnzwrJPmIXyGO6Tx5RXPvvnBbM5wR8odFrMgbcVdrdUXz-dwAaEpD9hduO6cZXsRDMw

Body:

{

"insert": ["respondentid1","respondentid2","respondentid3"]

}

The number of total respondents IDs supplied per API call should not exceed 2500.

3. Respondent ID Extraction

Allows configuration of parameter names used to extract respondent IDs from survey link

Example:

These defined parameter names can then be used in the survey link to extract the respondent IDs.

https://survey.mili.eu/tSqYnPRwnxj495fl2aK5vcMgAHLApnCLW12MfOZZ?sampleNameOne=respondentid1&sampleNameTwo=respondentid2

respondent IDs are extracted based on the priority order.
In this case, respondentid1 will be extracted due to higher priority

https://survey.mili.eu/tSqYnPRwnxj495fl2aK5vcMgAHLApnCLW12MfOZZ?sampleNameTwo=respondentid2

here, respondentid2 will be extracted

API Integration

Response Retrieval

Duis suscipit turpis at hendrerit pellentesque. Donec ornare urna eget elit malesuada blandit. Duis sed risus ac velit accumsan vehicula. Etiam elementum ante lorem, eu sollicitudin quam molestie ut. Vestibulum nec finibus ipsum, nec elementum velit.

Data Import

Curabitur sit amet tincidunt massa. Nullam aliquam congue metus. Suspendisse eu ante finibus, gravida metus vel, pharetra nisl. Aliquam quis lorem blandit velit luctus scelerisque eget quis metus. Aenean at nunc tristique, feugiat libero eu, condimentum nulla. Integer consequat, eros eu dignissim interdum, ante libero tincidunt risus, dignissim lobortis eros dolor eget leo. Maecenas ac nisl nec justo tempor vestibulum quis sed enim.

Webhook

Curabitur at rutrum tortor. Aenean posuere leo et elementum tristique. Quisque pretium at odio malesuada commodo. Curabitur ornare magna lacus, et suscipit purus lobortis eu. Morbi velit dui, cursus ut leo a, placerat dictum diam. Praesent dignissim fringilla felis, vitae tristique nisl bibendum ac. Quisque mollis ullamcorper libero sed euismod. Fusce et commodo lacus. Curabitur tincidunt felis id vestibulum interdum.