Authentication

Appropriate authentication is necessary to call most of the endpoints available on the DeepAffex Cloud.

Tokens

Authentication on the DeepAffex Cloud API uses JSON Web Tokens. Each token contains information about the current access request. On the Cloud, a token is mapped against an internal policy manager that determines what access levels it has. The token policies control access to the various parts of the API. Tokens are of three types:

• Device Token - A Device Token represents a single device. A Device Token provides access to endpoints that allow for device-specific features, for example, making measurements. To obtain a Device Token for the device in use, register your organizations License Key on the DeepAffex Cloud using the Organizations.RegisterLicense endpoint. A pair of tokens (a Device Token and a One-Time Refresh Token) is returned.

• User token - A User Token has the following two variations:

  • Nonmeasurement-related User Token - This is obtained using the Organizations.Login endpoint. This token doesn't contain a Device ID and provides access to most non-measurement related endpoints, for example, study management.
  • Measurement-related User Token - This is obtained using the Users.Login endpoint. Before obtaining this token, it's necessary to obtain a Device Token first. This token also contains a Device ID and can be used to carry out the measurements. It is required to associate measurements with a particular user account. This token can also be used for non-measurement endpoints exactly the same way as the first type.

• One-Time Refresh Token (OTRT) - This token is only used when calling the Auths.Renew endpoint. When you register a license or login with the user's credentials, a pair of tokens (a Device or User Token and a One-Time Refresh Token) is returned. To bind a new IP address and a new user agent to the Device Token or the User Token (or if the User Token expires) call the Auths.Renew endpoint with the OTRT. The client needs to send the matching pair of tokens to exchange it with a new pair. The old pair will not be valid after calling the Auths.Renew endpoint. This is used to ensure that devices can "roam" properly and improves token security.

Once you have obtained a token, it needs to be supplied in the header of all subsequent API calls as shown below:

Authorization: Bearer [token]

For WebSockets, if the supplied authorization details are incorrect, the connection will be refused and the socket dropped by the server. Upon a successful connection the socket will open and handshakes should be complete, signalling availability of the service.

More details and best practices

• Since tokens represent authentication information, please make sure to store them securely - typically in some form of secure storage.

• Some License Keys have a limited number of allowed active Devices. If you need to use your License on a different device, make sure to unregister your current device first by calling the Organizations.UnregisterLicense endpoint.

• To learn more about when to use Device Tokens vs User Tokens, please read about Anonymous Measurements. If the response to Organizations.RegisterLicense contains "SDK_DEVICE" as the RoleID, then you must use a User Token.

• Tokens may expire. To ensure that a token is valid, you can call the General.VerifyToken endpoint.

  • If the ActiveLicense field in the response is false, then your license is expired/decommissioned. Please use a different license or contact Nuralogix.
  • If the API returns an HTTP error 401 or 403, then the token is expired/invalid and the client must re-register the license.