Guidelines for Securing Your API Token

What is an API Token?

An API token is a refresh token that is used to generate an authentication token in order to sign in to the Own Data Platform via API, in order to perform various operations within the Own account.

Since the API token gives access to operations that can affect the data stored in your Own account, it should be treated just as securely as a username and password or any other authentication method.

In order to grant access to the Own API through a customer-developed client application via an API token, you are required to store that credential in such a way that your client application can read it to call the Own API.

Therefore, the protection of the API Token is taken entirely out of Own’s control and is totally dependent on the level of attention to application security requirements. Own strongly recommends applying some of the good practices listed here and to avoid any of the poor practices.

Examples of good practice for storing the API token as an application secret:

• The text string for the API Token is stored in Azure Key Vault and an app that wishes to retrieve that value needs to authenticate by presenting a client X.509 certificate.
  • Only the username for the process running the client application has access to the Client X.509 certificate to present it.
• ​​​​​​​​​​​​​​The text string for the API Token is stored in a configuration file which is read by the client application to obtain the value of the API Token. The configuration file is encrypted to prevent unauthorized access.
  • However, administrative users on the client application’s system would normally be able to un-encrypt the configuration file to obtain the value of the API Token.
  • Administrators on the client application’s system might not be the same employees who have administrative access to the customer’s Own Accounts.​​​​​​​

Examples of poor practice for storing the API token as an application secret:​​​​​​​

• Storing the API Token value as a string in an un-encrypted text file in the client application’s folder structure.
• Storing the API Token value as a string in an encrypted text file in the client application’s folder structure, but the encryption/decryption key is readily available.
• Storing the API Token value as a string variable in the source code of the client application, which might be a script that the customer changes whenever the Token API needs to be changed.
• Storing the API Token value as a string variable in a middleware integration application without encryption or appropriate masking.
• Sending an API Token as a plain value in the URL itself used for a call via a cUrl POST, PUT, PATCH or GET.