API Keys & OAuth

      API Keys & OAuth

        Article Summary

        There are two main ways to authorize (connect) your Close organization to third-party applications or your own internal system:

        • using API keys
        • using OAuth access

        Both methods are designed to help you automate and sync your sales process with other platforms while maintaining high levels of security and data privacy. Whether a third-party app uses an API key or OAuth to connect to Close depends on how the app's developers decided to set it up.

        API keys

        An API key is a secret token (like a password) which you can use to connect Close data to third-party applications or your own internal system.

        Creating an API key

        To create a new API key, go to Settings > Developer > API Keys and click + New API Key .

        Make sure to give your new API key an informative name so that you’ll be able to easily tell which key is used for which integration. Once done, you’ll be given the newly-generated API key, which you should copy and store securely. This key will not be displayed ever again (only the key's ID will be shown), so make sure to copy it.

        CleanShot 2023-06-20 at 10.55.30.gif

        API keys vs IDs

        An API key is a secret token, which is used to authenticate your requests to the Close API. It should be kept private and stored securely. On the other hand, an ID of an API key is just an identifier. It is safe to share.
        Don’t be confused by the similarity between the two. For example:

        API key ID: api_7b8KOSMa0OevK9qJvT6F9s

        API key: api_7b8KOSMa0OevK9qJvT6F9s.2H3Bt8ktGaQ9kVK45P7j7p (note: not a real key)
        The API key contains the ID, but it also contains a second secret part. Don’t ever share the full API key!

        Deleting an API key

        To delete an API key, click on the “…” next to the API key you’d like to delete.

        Note that deleting an API key will immediately cut off access to Close data from any integration using that key. You will not be able to restore a deleted API key.

        Reviewing existing API keys

        The best way to keep track of your API keys is to give them informative names and to use a separate API key for every integration. However, if that’s not enough, we provide you with some powerful clues that can help you determine what a specific API key is used for. Hover over the Last Used column and we will show you:

        • when the API key was used last
        • from what IP address
        • with what User Agent



        API keys are a great way to connect Close to your favorite applications or your own internal system. However, with great power comes great responsibility. API keys can read and modify all of your CRM data and should be handled very carefully.

        You should always store your API keys securely and you should never share them with parties you don’t trust. It is also recommended that you periodically create new API keys, update your integration(s), and delete the old API keys. This practice is typically referred to as “rotating” your API keys.

        OAuth access

        Third-party apps can use OAuth to request access to your Close organization, which involves a process where you can approve or deny the specific app's access to your Close data, rather than handling API keys directly.

        Allowing OAuth access

        To give a third-party app permission to access your Close account, navigate to the app and look for an option that says something like Connect to Close CRM. Selecting this will take you to a Close authorization page where you can approve the connection:

        CleanShot 2023-11-06 at 12.56.51@2x.png

        Once allowed, the third party app will get full read/write access to your Close organization (as determined by your Close role in case you're not a Close Admin).

        Can I change the scope (permissions) of the access?

        No. Currently, any third-party app using OAuth will obtain the same full access to your Close account as it would with an API key.

        Revoking OAuth access

        To revoke OAuth access to some of third party apps, go to your Settings > Accounts & Apps > Authorized Apps and click Revoke Access...

        CleanShot 2023-11-06 at 13.13.51@2x.png

        Note that revoking an OAuth access will immediately cut off access to Close data to that integration. The only way to restore the access it go to the third party app and request an access again.