Getting Started

This document should guide you through the authentication mechanism of the e-satisfaction API and help you understand common practices, errors and restrictions of the API.

Authentication - Domain, Tokens and Scopes

All API calls require authentication. This is essential for the API to identify which user is making the call so that appropriate results will be returned, as well as for security reasons.

Authentication is achieved through the use of an API key. e-satisfaction is using jwt and with a given working domain.

Working Domain

Working domain is the domain which is used to gather all your data in e-satisfaction, under the same organization. You should send your working domain on every API call so that we can identify your access to your organization.

You can find the working domain value in your organization settings.

User Tokens

User tokens can be generated on the application dashboard, visiting the user profile section. Creating a user token will request for a set of scopes so that the token can access the API. You can check the scopes needed in each API call in the present documentation.

It's your responsibility to keep the API tokens safe to prevent any unauthorized access. Once you obtain your API token, you will have to use it in every API call you make.

Read more about What is a token.

Examples

To include the token in an API call, simply add it as a header like this:

esat-auth: [jwt]
esat-domain: [yourdomain]

Header Example

esat-auth: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYXBpYXJ5Iiwic2NvcGUiOiJkb2MifQ.gJM_xMQt_MgfqDIoSIh3qK1V4cfpGsdRmy23LrjG03A
esat-domain: yourdomain

cURL Example

curl --header "esat-domain: yourdomain" --header "esat-auth: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjoiYXBpYXJ5Iiwic2NvcGUiOiJkb2MifQ.gJM_xMQt_MgfqDIoSIh3qK1V4cfpGsdRmy23LrjG03A" https://api.e-satisfaction.com/v3.2/q/questionnaire

Restrictions

All API endpoints are restricted using the token scopes. One token can call only a limited set of endpoints, defined in the scope field of the token, regardless of the access level of a user towards the platform.

Responses

The token is connected to a user, thus every call made to the e-satisfaction API represents the user that owns the token. This means that any manipulation in deletes or updates will be recorder on behalf of the user that owns the token.

Moreover, the API should be able to read the data that this particular user has access to. Sometimes users might have access to multiple Applications and/or Questionnaires. For this reason, you should make use of the Filters provided in the API documentation to filter your output accordingly.

Documentation

For a more detailed explanation and guide on the API authentication, feel free to read our official guide: https://esatisfactionv3.docs.apiary.io/#introduction/authentication