User Session

To use the Data360 Analyze REST APIs, you must first acquire an authentication token. This authentication token is then used in every subsequent request to authenticate access. We recommend that you release the token when it is no longer in use, as the REST API user will use one of the allocated user-based licenses.

The authentication can be passed in subsequent requests as a header parameter or query parameter named "ltk".

Get Supported Authentication Methods

Before authenticating, the client should identify the authentication methods supported by its tenant. The available authenticated methods are configured in the application and may be restricted by license. Data360 Analyze currently supports two authentication methods:

  • Username Password Authentication - the client passes a user name and password which is authenticated using Active Directory, LDAP, or Data360 Analyze itself, depending on configuration.

  • Siteminder Single-Sign-On - Authentication is delegated to the Siteminder SSO gateway. Data360 Analyze links the authenticated user to its corresponding Data360 Analyze profile.

A GET request is used to retrieve the supported authentication methods.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Response fields

Path Type Description

data.methods[0].name

String

The name of the method.

data.methods[0].initialUri

String

URI to call to initialisze the session.

data.methods[0].renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.methods[0].unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.methods[0].logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/methods?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
Host: localhost:8080

Example response

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

{"status":"OK","data":{"methods":[{"logoutUri":"/api/v3/logout/rest/authentication/username-password/initial","renewUri":"/api/v3/login/rest/authentication/username-password/renew","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","initialUri":"/api/v3/login/rest/authentication/username-password/initial","name":"username-password"}]}}

Acquire an authentication token using Username Password Authentication

A POST request is used to acquire the token.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

Path Type Description

username

String

The username.

password

String

The password.

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

POST /api/v3/login/rest/authentication/username-password/initial?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
Content-Length: 50
Host: localhost:8080

{ "username":"username","password":"userpassword"}

Example response

HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Sat, 26 Nov 2022 00:49:04 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 267

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","renewUri":"/api/v3/login/rest/authentication/username-password/renew","logoutUri":"/api/v3/logout/rest/authentication/username-password/initial"}}

Renew a token using Username Password Authentication

A session token has a finite lifespan. If the token has expired then it must be renewed. An error with the error code lae.security.authentication.sessionTimeout will be returned for any API call made using the expired token.

A `POST` request is used to renew the token.

Request headers

Name Description

ltk

token to renew

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

Path Type Description

username

String

The username.

password

String

The password.

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

POST /api/v3/login/rest/authentication/username-password/renew?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
ltk: tokenToRenew
Content-Length: 50
Host: localhost:8080

{ "username":"username","password":"userpassword"}

Example response

HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Sat, 26 Nov 2022 00:49:04 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 267

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","renewUri":"/api/v3/login/rest/authentication/username-password/renew","logoutUri":"/api/v3/logout/rest/authentication/username-password/initial"}}

Unlock a session using Username Password Authentication

If the Session Timeout property is configured then the session will be locked after the specified period of inactivity. An error with the error code lae.security.authentication.sessionLocked will be returned for any API call made using the locked token.

A POST request is used to unlock the session.

Request headers

Name Description

ltk

token to unlock

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

Path Type Description

username

String

The username.

password

String

The password.

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

POST /api/v3/login/rest/authentication/username-password/unlock?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
ltk: tokenToUnlock
Content-Length: 50
Host: localhost:8080

{ "username":"username","password":"userpassword"}

Example response

HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Sat, 26 Nov 2022 00:49:04 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 267

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/username-password/unlock","renewUri":"/api/v3/login/rest/authentication/username-password/renew","logoutUri":"/api/v3/logout/rest/authentication/username-password/initial"}}

Release an authentication token using Username Password Authentication

A GET request is used to release the token.

Request headers

Name Description

ltk

token to logout

Request fields

None

Response fields

Path Type Description

status

String

HTTP Status Code.

Example request

GET /api/v3/logout/rest/authentication/username-password/initial HTTP/1.1
Content-Type: application/json;charset=UTF-8
ltk: tokenToLogout
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 15

{"status":"OK"}

Acquire an authentication token using Siteminder SSO Authentication

The Siteminder SSO User should be passed in the header. The default parameter name for the User is SM_USER. A GET request is used to acquire the token.

Request headers

Name Description

SM_USER

User name.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

NONE

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/siteminder-sso/initial?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
SM_USER: username
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Sat, 26 Nov 2022 00:49:04 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 258

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/siteminder-sso/unlock","renewUri":"/api/v3/login/rest/authentication/siteminder-sso/renew","logoutUri":"/api/v3/logout/rest/authentication/siteminder-sso/initial"}}

Renew a session using Siteminder SSO Authentication

A session token has a finite lifespan. If the token has expired then it must be renewed. An error with the error code lae.security.authentication.sessionTimeout will be returned for any API call made using the expired token. The Siteminder SSO User should be passed in the header. The default parameter name for the User is SM_USER.

A `GET` request is used to renew the token.

Request headers

Name Description

ltk

Token to renew.

SM_USER

User name.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

None

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/siteminder-sso/renew?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
SM_USER: username
ltk: tokenToRenew
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Sat, 26 Nov 2022 00:49:04 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 258

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/siteminder-sso/unlock","renewUri":"/api/v3/login/rest/authentication/siteminder-sso/renew","logoutUri":"/api/v3/logout/rest/authentication/siteminder-sso/initial"}}

Unlock a session using Siteminder SSO Authentication

If the Session Timeout property is configured then the session will be locked after the specified period of inactivity. An error with the error code lae.security.authentication.sessionLocked will be returned for any API call made using the locked token.

The Siteminder SSO User should be passed in the header. The default parameter name for the User is SM_USER.

A GET request is used to unlock the token.

Request headers

Name Description

ltk

Token to unlock.

SM_USER

User name.

Request parameters

Parameter Description

tenantLocator

Tenant Locator

Request fields

None

Response fields

Path Type Description

data.token

String

The authentication token.

data.unlockUri

String

URI to call to unlock the session after locking due to timeout.

data.renewUri

String

URI to call to renew the authentication token for the session to prevent timeout.

data.logoutUri

String

URI to call to logout of the session.

status

String

HTTP Status Code.

Example request

GET /api/v3/login/rest/authentication/siteminder-sso/unlock?tenantLocator=object:!tenant:defaultTenant HTTP/1.1
ltk: tokenToUnlock
SM_USER: username
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Set-Cookie: analyze_ltk=returnedToken; Path=/; Domain=localhost; Max-Age=28800; Expires=Sat, 26 Nov 2022 00:49:04 GMT; HttpOnly; SameSite=Strict
Content-Type: application/json
Content-Length: 258

{"status":"OK","data":{"token":"returnedToken","unlockUri":"/api/v3/login/rest/authentication/siteminder-sso/unlock","renewUri":"/api/v3/login/rest/authentication/siteminder-sso/renew","logoutUri":"/api/v3/logout/rest/authentication/siteminder-sso/initial"}}

Release an authentication token using Siteminder SSO Authentication

A GET request is used to release the token.

Request headers

Name Description

ltk

Token to logout.

Request fields

None

Response fields

Path Type Description

status

String

HTTP Status Code.

Example request

GET /api/v3/logout/rest/authentication/siteminder-sso/initial HTTP/1.1
Content-Type: application/json;charset=UTF-8
SM_USER: username
ltk: tokenToLogout
Host: localhost:8080

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 15

{"status":"OK"}