Intercom API Authentication: Methods, Credentials, and Security

Authentication overview

Authentication for the Intercom API is a critical security measure that verifies the identity of an application or user attempting to interact with Inter platform resources. By ensuring that only authorized entities can make requests, Intercom protects customer data and maintains the integrity of its services. The API supports industry-standard authentication protocols, enabling developers to integrate securely whether building internal tools or public applications. Proper authentication implementation is essential for maintaining the confidentiality and integrity of customer conversations, user data, and business workflows managed within Intercom.

Intercom's approach to authentication aligns with common API security practices, emphasizing the use of strong credentials and secure communication channels. All API interactions are required to use HTTPS/TLS to encrypt data in transit, protecting against eavesdropping and tampering. Developers are advised to follow Intercom's security best practices when handling API keys and OAuth tokens to prevent unauthorized access.

Supported authentication methods

The Intercom API provides two primary methods for authentication, catering to different integration scenarios:

1. API Keys (Bearer Tokens): This method is suitable for server-to-server communication, backend applications, internal scripts, and development environments. An API key grants direct access to Intercom resources associated with the generating workspace. It is typically passed as a Bearer token in the Authorization header of HTTP requests.
2. OAuth 2.0: Designed for third-party applications and integrations that require delegated access to a user's Intercom workspace without handling their credentials directly. OAuth 2.0 enables users to grant specific permissions to an application, ensuring that the application only performs actions within those defined scopes. Intercom primarily uses the Authorization Code Grant type, which is recommended for web applications.

Comparison of Authentication Methods

Choosing the correct authentication method depends on the nature of your integration. For applications where a user explicitly grants your application permission to access their Intercom data, OAuth 2.0 is the more secure and appropriate choice. For backend services that operate without direct user interaction but require full API access to a specific workspace, API keys are often simpler to implement.

Getting your credentials

The process for obtaining credentials varies based on the chosen authentication method:

For API Keys:

1. Log in to Intercom: Access your Intercom workspace as an administrator.
2. Navigate to Developer Hub: Go to Settings > Developers > Developer Hub.
3. Create a New App: If you haven't already, create a new app within the Developer Hub. This app will be linked to your API key.
4. Generate Access Token: Under your app's settings, find the "Authentication" section and generate a new Access Token (API Key). You will typically be presented with a single, long string. This is your API key.
5. Store Securely: Immediately copy and store this API key in a secure location. Intercom will only display the full key once. Treat it like a password; do not hardcode it directly into client-side code or public repositories. For best practices, consider using environment variables or a secrets management service.

For detailed steps, refer to the Intercom API Authentication guide.

For OAuth 2.0:

1. Register Your Application: Go to Settings > Developers > Developer Hub in your Intercom workspace. Create a new application.
2. Configure OAuth Settings: Within your app's settings, navigate to the "Authentication" section. Here, you will need to specify:
   • Redirect URLs: The endpoint(s) on your server where Intercom will send the user after they authorize your application.
   • Client ID: This is automatically generated when you create your app.
   • Client Secret: This is also automatically generated. Keep this secret confidential and never expose it in client-side code.
3. Define Scopes: Select the specific permissions (scopes) your application requires to access Intercom resources. Only request the minimum necessary scopes to adhere to the principle of least privilege.
4. Implement the OAuth Flow: Your application will initiate the OAuth flow by redirecting users to Intercom's authorization endpoint, where they grant permission. Intercom then redirects the user back to your specified Redirect URL with an authorization code. Your application exchanges this code for an access token and refresh token using your Client ID and Client Secret.

The Intercom OAuth 2.0 documentation provides comprehensive instructions for implementing the authorization flow.

Authenticated request example

Below are examples demonstrating how to make an authenticated request using both API keys and OAuth 2.0 tokens.

Using an API Key (Bearer Token) with cURL:

This example retrieves a list of conversations using a securely stored API key.

curl -X GET \
  'https://api.intercom.io/conversations' \
  -H 'Authorization: Bearer YOUR_INTERCOM_API_KEY' \
  -H 'Accept: application/json'

Replace YOUR_INTERCOM_API_KEY with your actual API key.

Using an OAuth 2.0 Access Token with Python (requests library):

This example demonstrates fetching a user's data after obtaining an OAuth access token.

import requests

ACCESS_TOKEN = "YOUR_OAUTH_ACCESS_TOKEN"  # Obtained after the OAuth flow
USER_ID = "654321"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Accept": "application/json"
}

response = requests.get(f"https://api.intercom.io/users/{USER_ID}", headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

Replace YOUR_OAUTH_ACCESS_TOKEN with the access token retrieved during your OAuth 2.0 flow and USER_ID with a valid Intercom user ID.

Security best practices

Securing your Intercom API integration is paramount to protecting sensitive customer data. Adhering to these best practices helps mitigate common security risks:

1. Protect Your Credentials:
   • API Keys: Never hardcode API keys directly into source code, especially for client-side applications. Store them in environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault). Restrict access to these storage locations.
   • Client Secrets (OAuth): Treat your OAuth Client Secret with the same level of confidentiality as API keys. It must only be known to your server-side application and Intercom.
2. Use HTTPS/TLS Everywhere: All communication with the Intercom API must occur over HTTPS. This encrypts data in transit, preventing unauthorized interception and ensuring data integrity. Intercom enforces HTTPS for all API endpoints.
3. Principle of Least Privilege:
   • OAuth Scopes: When configuring OAuth 2.0, request only the minimum necessary API scopes that your application requires to function. Overly broad permissions increase the risk if your access token is compromised.
   • API Key Access: While API keys generally grant broad access to a workspace, ensure the context in which they are used aligns with the necessary permissions.
4. Regularly Rotate Credentials: Periodically rotate your API keys and OAuth Client Secrets. This limits the window of exposure if a credential is ever compromised. Intercom's Developer Hub allows you to generate new API keys and revoke old ones.
5. Handle Access Tokens Securely (OAuth):
   • Storage: Store OAuth access tokens securely on your server backend. Avoid storing them in client-side storage (e.g., local storage, session storage) where they could be vulnerable to XSS attacks.
   • Refresh Tokens: If using refresh tokens, store them with even greater security than access tokens, as they can be used to obtain new access tokens.
   • Expiration: Be aware of access token expiration times and implement mechanisms to refresh them using refresh tokens (if applicable) or re-initiate the OAuth flow when necessary.
6. IP Whitelisting (if available/applicable): If your infrastructure supports it, configure IP address whitelisting on your Intercom app settings to only allow API requests from known, trusted IP addresses. This adds an extra layer of security against unauthorized access attempts.
7. Error Handling and Logging: Implement robust error handling for authentication failures and log relevant security events. Monitor these logs for suspicious activities, such as repeated failed authentication attempts.
8. Secure Development Practices: Follow general secure coding practices, including input validation, protection against SQL injection and cross-site scripting (XSS), and dependency scanning, to minimize vulnerabilities in your application that could lead to credential compromise. Developers can consult resources like the OWASP Top 10 for common web application security risks and mitigation strategies.

By diligently implementing these security measures, developers can build robust and secure integrations with the Intercom API, safeguarding both their applications and their users' data.