API keys¶

To use the Awaretrain API, you require a valid API key with the necessary scopes. See authentication on the getting started page for details on how to implement authentication.

On this page, you will find all information on how to manage API keys and keep them secure.

Managing API keys¶

1. Make sure your account has the super manager role.
2. Navigate to the Settings menu item and select API Keys.

   

On this page, you will see a list of created API keys along with their expiration date. From here, new API keys can be created, and existing keys edited or deleted.

Creating a new API key¶

1. Click New API Key.

2. You will be prompted with the Create API Key page.

   

   • Name: A descriptive name for the API key.
   • Expires at: Date after which the API key expires and can no longer be used. Keep this date as short as possible, not longer than a year.
   • Scope (permissions): Scopes determine what resources can be accessed and what operations can be performed on those resources (e.g. read users). A detailed overview of all scopes can be found on the scopes page.
   • IP whitelist (optional): For additional security, you may restrict the API key usage to one or more specific IP addresses. Enter one IP address per line (either IPv4 or IPv6). Wildcards or ranges are not supported.

3. Click Save button. A dialog will show you the created API key. This is the only time you get to see the API key so copy it and store it somewhere safe. See security considerations on how to best store your API key and keep it secure.

Security considerations¶

• Create a new API key for every application with a minimal set of scopes required for the application to work. In case the API key is leaked, the key can be deleted and a new one created without affecting other integrations.
• Use the IP whitelist option when creating API keys to prevent attackers from gaining access in case an API key is leaked.

Storing the API key¶

• Use secure key management systems (KMS) to store secret keys. When you create an API key from the Awaretrain platform, it is only revealed once. Immediately copy the key to a KMS, which is designed to handle sensitive information with encryption and access controls.
• Follow best practices on keeping secrets safe depending on what programming language and framework you use for your application. If your application requires the API key to be stored in the database, consider storing it encrypted.
• Do not store keys in source code repositories (such as GitHub). Attackers are known to scan public repositories for credentials. Due to the nature of source code repositories, it is very tough or even impossible to correct this mistake if a key has been stored in version control accidentally. If this happens, immediately delete the API key using the management page and create a new key.