Security Settings

API Authentication

Engine authenticates API requests using either Basic Auth or Bearer tokens. 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).

API Credentials

To get started with the V2 API, you can add Basic Auth credentials to the ApiBasicSystemAccounts property in the file. The value for this setting should be a newline-delimited list of username/password pairs in the format of username:password.

Of course, passwords residing in a configuration file isn't always desirable, and credentials set in the ApiBasicSystemAccounts property have access to every API endpoint. To create credentials that persist in the database with narrower functionality, use the admin tool or make a POST to the /appManagement/credentials endpoint.

For example, to create an API account with the ability to create and delete registrations for a specific tenant and course, the POST body would contain scoping properties and resemble the below example.

  "name": "eLearnersUnite-Registrations",
  "permissions": {
    "scopes": [
    "tenantName": "eLearnersUnite",
    "courseId": "acb74ebb-74b3-48e1-8c5d-587b5da01374"

Whether you create a credential with the admin tool or API, the response will include the new credential's user name and password.

    "id": "RfKr3qtxveuCW7b9wXs",
    "secret": "IbyJLCRYWw55qf2q3tE"

If you wanted to remove the ApiBasicSystemAccounts property from your file entirely, create a credential with an empty scopes array. This account will have the equivalent 'root' access of an ApiBasicSystemAccounts credential.

  "name": "system-admin",
  "permissions": {
    "scopes": [

The complete list of scopes can be viewed in either the admin tool or by accessing the /about endpoint. They are also included with a short description in the table below:

Scope Description
read Grants read access
write Grants write access
delete Grants deletion access
admin Grants read, write, and account management access
admin:read Grants read-only admin access
admin:createTenant Grants tenant creation access
admin:deleteData Grants ability to delete an entire tenants data or do PII deletion
admin:writeConfiguration Grants write administrative configuration settings
admin:writeCredential Grants ability to create a credential
admin:connector Grants access to administer content connectors
read:connectorContent Grants access to read content connector list of available content
read:course Grants read access to course resources
write:course Grants write access to course resources
delete:course Grants deletion access to course resources
read:dispatch Grants read access to dispatch resources
write:dispatch Grants write access to dispatch resources
delete:dispatch Grants deletion access to dispatch resources
read:ping Grants read access to the ping resource
read:about Grants read access to about resource
read:registration Grants read access to registration resources
write:registration Grants write access to registration resources
delete:registration Grants deletion access to registration resources
read:xapicredential Grants read access to xapi credential resources
write:xapicredential Grants write access to xapi credential resources
delete:xapicredential Grants deletion access to xapi credential resources
read:xapipipe Grants read access to xapi pipe resources
write:xapipipe Grants write access to xapi pipe resources
delete:xapipipe Grants deletion access to xapi pipe resources
configure:server Includes server administrator settings when managing configuration
request:secrets Grants read access to encrypted configuration settings
write:player Grants write access to the player resources
read:player Grants read access to the player resources
read:contentVault Grants read access to the content vault resources

Certain scopes are used only for LTI 1.3 launch and should not be used manually. These scopes and their uses are described in the table below:

Scope Description Grants read access to line item resources (for LTI 1.3 only) Grants write access to scores resource (for LTI 1.3 only) Grants read access to results resources (for LTI 1.3 only)
lti13:registration Grants write access to an internal resource used for LTI 1.3 launch

Token Authentication

If interfacing with Engine primarily through a user-facing, front-end application, consider authenticating these API calls using short-lived bearer tokens.

Obtain a scoped token serverside by making a POST to /appManagement/token. The scoping syntax is similar to creating a scoped API credential, but the request body also includes an 'expiry' name/value pair to specify when the token expires.

  "permissions": {
    "scopes": [
    "tenantName": "eLearnersUnite",
    "courseId": "6b384cd4-82a9-475d-baa1-3a2b25104920",
  "expiry": "2020-04-27T19:50:15.212Z"

This will return a URL-safe token that you can send back to the client.

    "result": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1ODgwMTcwMTUsInNjb3BlcyI6WyJ3cml0ZTpjb3Vyc2UiXSwidGVuYW50IjoiZGVmYXVsdCIsImNvdXJzZSI6Ik15Q291cnNlSWQxMjMifQ.WE-OSa9cLGQxPwSNunxSNyrld-Ji4sQsC7d7kBXbuCw"

The client making the API request specified in the scope can then use the token for Bearer Token authenication instead of Basic Auth. This method will allow your client application to make API requests without exposing your API credentials.


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.

In order to support password rotation (that is, the ability to switch to a new encryption password while still decrypting values encrypted with the old password), set PreviousEncryptionPassword with the current password's value before changing it. If the previous password is given and decryption of a configuration setting fails with the current password, Engine will attempt to use the previous password. To facilitate password rotation, Engine provides the /appManagement/configuration/updateEncryptedSettings API endpoint. When that endpoint is POST-ed to, Engine will rewrite encrypted settings (and xAPI statement pipe passwords) for that tenant using the latest password. A PreviousEncryptor setting also exists if you need to change the encryption algorithm.

All in all, the password rotation process is as follows:

This rotation process does not handle package- or registration-level settings. The only such settings that are encrypted by default are the registration postback credentials. We recommend that you set those credentials at the tenant level instead of providing different credentials for each registration, to avoid needing to come up with your own process to re-write those settings when you rotate passwords.

Encrypted values are decrypted immediately after they are loaded. In particular, note that settings which are encrypted in the DB may be shown decrypted when returned via the API if the includeSecretSettings query parameter is used.


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.

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