Best practices

Follow these best practices to improve the security and performance of your ICR App.

Select the minimum permissions required

When you register an ICR App, select the minimum permissions that your ICR App needs. If any keys or tokens for your app become compromised, this will limit the amount of damage that can occur. For more information about how to choose permissions, see "Choosing permissions for an ICR App."

Webhooks > polling

Currently this is not a worry but sometime in the future we will implement rate limiting for ALL apps. But apps will be alerted about this before it is rolled out.

Subscribe to webhook events instead of polling the API for data. This will help your ICR App stay within the API rate limit. For more information, see "Using webhooks with ICR Apps".

Secure your app's credentials

You can generate a private key and webhook secret for your ICR App. With these credentials, your app can generate installation access tokens and verify webhook requests. These tokens can be used to make API requests on behalf of an app installation.

You must store these credentials securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using.

Private keys

The private key for your ICR App grants access to every organization that the app is installed on.

The private key is the single most valuable secret for an ICR App. So make sure it is securely stored. You can store the key as an environment variable but just make sure you know the security implications of doing that. If an attacker gains access to the environment, they can read the private key and gain persistent authentication as the ICR App.

You should not hard-code your private key in your app, even if your code is stored in a private repository.

Installation access tokens

Installation access tokens are used to make API requests on behalf of an app installation. Your app can use its private key to generate an installation access token.

If your app is a website or web app, you should encrypt the tokens on your back end and ensure there is security around the systems that can access the tokens.

Installation access tokens livetime is ~2hours to minimize damage if an app developers system is attacked and tokens stolen.

Make a plan for handling security breaches

You should have a plan in place so that you can handle any security breaches in a timely manner.

In the event that your app's private key is compromised, you will need to generate a new key, update your app to use the new key, and delete your old key.

In the event that installation access tokens are compromised, you should immediately revoke these tokens. For more information, see "ICR App installations" to revoke an installation access token.

Use a webhook secret

You should set a webhook secret for your ICR App and verify that the signature of incoming webhook events match the secret. This helps to ensure that the incoming webhook event is a valid ICR event.

For more information, see "Using webhooks with ICR Apps."

Allow time for users to accept new permissions

When you add project or organization permissions to your ICR App, users who have the app installed on their organization will receive an email prompting them to review the new permissions. Until the user approves the new permissions, their app installation will only receive the old permissions.

When you update permissions, you should consider making your app backwards compatible to give your users time to accept the new permissions. You can use the installation webhook with the newPermissionsAccepted action property to learn when users accept new permissions for your app.