Authentication

User Sessions

/gatekeeper

User sessions are primarily utilised via Analytics Cloud Web UI and other automated setup utilities / tests. A client_id and client_secret are required from the system operator to identify the client application initiating each session.

A username and password are also required before continuing.

Login

POST /gatekeeper

Initiates or renews a new user session by supplying user and client credentials or refreshing an existing token. This endpoint follows the OAuth 2.0 specification and implements the Resource Owner Password Credentials Grant.

To start a session, both username and password are required plus "grant_type": "password". To renew an existing session, use the returned refresh_token with "grant_type": "refresh_token".

Warning

Starting a new session will terminate all prior active sessions for that user

The OAuth 2.0 specification requires that the request body be sent in the application/x-www-form-urlencoded format.

Example public client request:

POST /gatekeeper HTTP/1.1
Host: analytics.actual-experience.com
Origin: https://analytics.actual-experience.com
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=this-is-my%40email-address.com&password=923ghpkjsdbfwl23IUH0%25uh3-9jd

However for backwards-compatibility, the request body may be in JSON format:

POST /gatekeeper HTTP/1.1
Host: analytics.actual-experience.com
Content-Type: application/json

{
  "grant_type": "password",
  "username": "this-is-my@email-address.com",
  "password": "923ghpkjsdbfwl23IUH0%uh3-9jd",
  "client_id": "PAN3dWFtrXHwZXJAZW5jZvDlylVO",
  "client_secret": "t7H0sMl9e3a8"
}

• grant_type : required "password" | "refresh_token"

• username : optional your email address used to grant access to other APIs – only necessary when "grant_type": "password"

• password : optional the password used to grant access to other APIs – only necessary when "grant_type": "password"

• refresh_token : optional send a previously received refresh_token – only send while
  "grant_type": "refresh_token" when an access_token has expired.

• device_token : optional If the client has a device token as returned from a previous
  2-Factor Authentication initiated session then this should be supplied here.

• client_id : optional unique id used to identify the client making the request - only necessary for confidential clients

• client_secret : optional unique string assigned to the client making the request - only necessary for confidential clients

Response

HTTP/1.1 200 OK

{
  "access_token": "RKKbse3UubfZ14B1WWrKnsq+/Ye+Ln+XZ/cQl81Uy9ky004Ttlc+pw==",
  "refresh_token": "THJKY8xBktweh1dHlnsKyNBfPk1xxtJbuwcqmX2/5ufI3Ok5H0O4Rw==",
  "token_type": "Bearer",
  "expires_in": 3600,
  "userCtx": {
    "partner": "part1",
    "organisation": "org1"
  },
  "username": "user@example.com",
  "authorisedAreas": {
    "results": true
  },
  "authorisedComponents": [
    "system behaviour",
    "measurement explorer",
    "event manager",
    "dashboard view",
    "supply chain triage",
    "experience history",
    "agent analyser",
    "dashboard manager",
    "analytics configuration",
    "event subscriber"
  ],
  "notificationUri": "part1/org1/user/myusername/notification",
  "settingsUri": "part1/org1/user/myusername/notification",
  "userUri": "part1/org1/user/myusername"
}

If the user is required to use 2-Factor Authentication the following response will be returned instead of the successfully created session response above. From this point onwards the 2FA login process should be followed.

EULA Challenge Response

HTTP/1.1 430 Unauthorized

{"reason":"requireEula"}

Warning

Integrations must not sign EULAs. Please first login interactively to accept our terms before continuing.

2FA Challenge Response

HTTP/1.1 401 Unauthorized

{
  "reason": "twoFAChallenge",
  "twoFAChallengeUri": "twoFAChallenge/0c0b9837b8a0619050b0eec5130f6713"
}

Warning

Integrations cannot not use 2FA.

Refresh Token

It is necessary to refresh an access token when it has expired. To do this, pass the previously received refresh_token and set "grant_type": "refresh_token". You'll get back a brand new access_token and refresh_token to continue the session.

{
  "grant_type": "refresh_token",
  "refresh_token": "THJKY8xBktweh1dHlnsKyNBfPk1xxtJbuwcqmX2/5ufI3Ok5H0O4Rw==",
  "client_id": "PAN3dWFtrXHwZXJAZW5jZvDlylVO",
  "client_secret": "t7H0sMl9e3a8"
}

Response

HTTP/1.1 200 OK

{
  "access_token": "BNNbse3UubfZ14B1WWrKnsq+/Ye+Ln+XZ/cQl81Uy9ky004Ttlc+pw==",
  "refresh_token": "GYJKY8xBktweh1dHlnsKyNBfPk1xxtJbuwcqmX2/5ufI3Ok5H0O4Rw==",
  "token_type": "Bearer",
  "expires_in": 3600
}

Logout

DELETE /gatekeeper Ends a user session as initiated by a previous POST request.

Response

HTTP/1.1 200 OK

{
  "ok": true
}