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.

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

Request parameters

Parameter Description

Parameter	Description
`tenantLocator`	Tenant Locator

tenantLocator

Tenant Locator

Response fields

Path Type Description

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.

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

Parameter	Description
`tenantLocator`	Tenant Locator

tenantLocator

Tenant Locator

Request fields

Path Type Description

Path	Type	Description
`username`	`String`	The username.
`password`	`String`	The password.

username

String

The username.

password

String

The password.

Response fields

Path Type Description

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.

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=Wed, 31 May 2023 11:10:09 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

Name	Description
`ltk`	token to renew

ltk

token to renew

Request parameters

Parameter Description

Parameter	Description
`tenantLocator`	Tenant Locator

tenantLocator

Tenant Locator

Request fields

Path Type Description

Path	Type	Description
`username`	`String`	The username.
`password`	`String`	The password.

username

String

The username.

password

String

The password.

Response fields

Path Type Description

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.

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=Wed, 31 May 2023 11:10:09 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

Name	Description
`ltk`	token to unlock

ltk

token to unlock

Request parameters

Parameter Description

Parameter	Description
`tenantLocator`	Tenant Locator

tenantLocator

Tenant Locator

Request fields

Path Type Description

Path	Type	Description
`username`	`String`	The username.
`password`	`String`	The password.

username

String

The username.

password

String

The password.

Response fields

Path Type Description

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.

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=Wed, 31 May 2023 11:10:09 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

Name	Description
`ltk`	token to logout

ltk

token to logout

Request fields

None

Response fields

Path Type Description

Path	Type	Description
`status`	`String`	HTTP Status Code.

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"}