Security Settings

API Authentication

In order to keep your credentials secure we strongly recommend using TLS (https) when accessing the API, and using long random strings for both the username and password components (these should not be real user accounts, so no one should ever have to type these credentials).

Engine's API is designed to exclusively be used by your team during application development and by your application in production. It does not provide the fine grained security control you'd want for an API available to users, as any API account can perform any operation, including the creation and deletion of data. The API is not authenticated in such a way that would be safe for a user-facing application to call directly. The ability to set up multiple accounts is only relevant for the purpose of having different sets of credentials that can be revoked separately. Only use the API as an interface between your application and Engine.


If EncryptionPassword is provided and EncryptConfigurationSettings is set to true, configuration settings with the secretString type will be encrypted when set via the API. By default, Engine will use 128-bit AES encryption with GCM as its encryption algorithm, but a custom encryption algorithm can be set via the Encryptor configuration setting.


If HashAccountPasswords is enabled, then when storing "account" configuration settings, passwords will be replaced with bcrypt password hashes before being persisted to the database. The originally specified password will not be saved anywhere, so when reading this setting through the API, only the hashed password will be seen. In order to "bootstrap" Engine so that no unhashed passwords appear in configuration files, one can do the following:

  • In your Engine config file, set HashAccountPasswords to true and define a set of temporary credentials for API access using ApiBasicSystemAccounts.
  • Using those temporary credentials, you can then create persistent credentials by POSTing to /appManagement/credentials. You can create credentials with access to a single tenant by specifying a header with the name engineTenantName and a value specifying the name of the tenant that the credentials will be scoped to. If you do not specify an engineTenantName, then the credentials will work for every tenant within your Engine installation.
  • After creating your credentials through the API, remove the temporary credentials from your configuration file. From now on, you can use the new persistent credentials to create any other credentials that you may need in the future.

Alternatively, if you have a method of generating bcrypt hashed passwords, you can create your own password hashes and use them instead of passwords in any "accounts" configuration setting, even directly in your configuration file. We expect these to be in the modular crypt format with a prefix of 2a, 2b, or 2y.

The built-in xAPI Statement Viewer will not work if password hashing is enabled. Customers wishing to use Statement Viewer in their application are advised to download and configure the original open-source Statement Viewer.

results matching ""

    No results matching ""