Skip to main content

Automation and API Credentials

We often need to configure automated access to services for our integrations and custom functionality. This is normally done by generating API credentials for the service, or creating a machine user. This document outlines some of the best practices that we follow when provisioning and managing automated access.

Don’t use personal credentials​

When setting up automated integrations, don’t use the API credentials or user assigned to a particular person. People regularly change roles, teams and employers and this can impact the access level and validity of their credentials. You don’t want the integration to break because whoever set it up has left the business and their account has been deactivated.

If you’re setting up an API integration, create a dedicated set of API credentials for the purpose of that integration and make sure the credentials are named and documented appropriately so their purpose is clear.

If you need user access for an integration, create a machine user - a user that is not associated with an individual and is only used for automated access. Make sure the user is documented sufficiently so its purpose is clear.

Set the appropriate permissions​

Just like with user access, we follow the principle of least privilege for automation users and credentials. This means that the credentials should only be valid for the purposes that they were generated for, and nothing else.

When you are creating API credentials, the service may let you choose the scopes that the credentials can access, the user role that the credentials are given, or a list of endpoints that they’re allowed to call. Make sure you only select the endpoints that your integration needs right now. If the needs of the integration change, the credentials can always be regenerated with additional permissions.

When you’re creating a machine user, give them the role and permissions appropriate to match their purpose. Restricting machine users is even more important than individual users, because the credentials for the user will be out there, utilised by an app that may contain security vulnerabilities.

This also means that credentials should never be re-used for additional purposes, as it makes it difficult to restrict the permissions on them. Each integration should have its own unique set of credentials.

Protect the credentials​

When you use API credentials or machine user credentials in an application, you must make sure that the credentials can not be easily accessed and abused by malicious actors.

Never commit any API credentials to source control. Doing so exposes you to the additional risk, because anyone who gains unauthorised access to the repository would also gain access to the credentials. Even if you commit them temporarily and then remove them later, they will be accessible in the repository history (unless you go through the painstaking process of wiping the changes from the commit history). Instead the credentials should be configured directly in the application or environment where they are used.

When configuring credentials in an application, use the most secure method available for your situation:

  • Most cloud platforms provide functionality to securely manage secrets, making them only available to service users with relevant permissions. This method should be preferred and used whenever possible.

  • Alternatively, the service or application may allow you to save an environment variable as a password, allowing you to set and update it, but not view the information. This is a good fallback for storing credentials.

  • Storing credentials in plain-text environment variables should be the last resort fallback when a more secure method is not available.

If you need to store the credentials for safekeeping or share them with other members of the team, make sure you use a secure method for it such as a Password Manager. However, ideally you shouldn’t store the credentials anywhere after you’ve configured them in the relevant app or integration. API credentials can easily be regenerated when needed, so there’s little reason to store them outside the purpose they were generated for.