About token-based authentication#

EclecticIQ Intelligence Center supports user authentication through user name/password validation and JWT Bearer session tokens, as well as opaque API tokens to programmatically integrate EclecticIQ Intelligence Center with external systems and services.

About token-based authentication in EclecticIQ Intelligence Center#

EclecticIQ Intelligence Center supports token-based authentication.

EclecticIQ Intelligence Center authentication mechanism is based on JSON Web Token (JWT).

The token header contains an issued-at timestamp, which is used to check token validity.

By default, the token expires 30 minutes after successfully signing in to a Intelligence Center user session.

Before expiring, a pop-up dialog notifies users that their session is about to be terminated.

Users can choose to continue the current session, or to let it expire.

When the token expires the corresponding session is terminated, and users are automatically logged out.

They need to sign back in to EclecticIQ Intelligence Center if they want to resume working.

When users sign out of EclecticIQ Intelligence Center, the JSON web token related to the web session they just terminated is revoked, and it is no longer valid.

This prevents reusing the token for unauthorized access.

When human interaction is detected — for example, keystrokes or mouse activity — the token is automatically refreshed every 60 seconds.

This prevents the system from signing out users who may be working or saving data at that time.

Therefore, the default maximum amount of idle time without any human interaction before being automatically signed out equals to session token validity - 1 minute.

Authenticate#

To authenticate and to access EclecticIQ Intelligence Center with user name and password credentials:

  1. Make a POST request to the /auth API endpoint.

  2. In the request, pass valid username and password authentication credentials as a JSON object to the /auth endpoint.

  3. The validated credential data is used to generate a Bearer token that is returned with the response.

  4. Include the Bearer token value in any subsequent API requests.

  5. Pass the token by including an Authorization HTTP header in the API request.

    The Authorization HTTP header has the following format:

    Authorization: Bearer ${token}

Auth endpoint#

API endpoint

/auth

Auth method

POST

HTTP headers

"Content-Type: application/json"

"Accept: application/json"

API request

POST + "Content-Type: application/json" + "Accept: application/json" + { "username": "${username}", "password": "${password}" } + https://${platform_host}/api/auth

API response

{ "expires_at": "${expiration_timestamp}", "token": "${token}" }

Auth request#

The following example authenticates with a cURL request:

# Authenticate with username and password
curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"username": "[email protected]", "password": "bug#1"}' \
    --url https://${platform_host}/auth

Auth response#

If the user name and password credentials are valid, the POST request returns a JSON web token:

# Response: Bearer token for the web session
{
  "expires_at": "2019-07-14T12:41:10.063375+00:00",
  "token": "eyJhbGciOiJU ... wiZ1oxNTEwaTIyNDcwfQ.eyJ1c2VyX2lk1jo3fQ.3o65E263hSGf4od5o4eoME2GRF-CnYJvaVg69YTq9HU"
}

Example#

# Example: request a complete list of content blocks belonging to the selected feed
curl -X GET \
    -v \
    --insecure \
    -i \
    -H "Content-Type: application/json" \
    -H "Authorization:Bearer eyJhbGciOiJU ... wiZ1oxNTEwaTIyNDcwfQ.eyJ1c2VyX2lk1jo3fQ.3o65E263hSGf4od5o4eoME2GRF-CnYJvaVg69YTq9HU" \
    --url https://${platform_host}/feeds/downloads/200

Note

About cURL calls

  • If you make HTTPs cURL calls to the API, and if you have a self-signed or an invalid certificate, include the -k or the --insecure parameter in the cURL call to skip the SSL connection CA certificate check.

  • Always append a / forward trailing slash at the end of an API URL endpoint.

    The only exception is /auth, which does not take a forward trailing slash.

  • In the cURL call, the -d data payload with the entity information must be flat JSON, not hierarchical JSON.

    To pass a hierarchical JSON object, include the --data-binary parameter, followed by the path to the JSON file, for example @/path/to/entity_file.json

    Example: --data-binary @/path/to/entity_file.json