Intercom Authentication: API Keys, OAuth 2.0, and Webhooks

Authentication overview

Intercom provides methods for authenticating access to its API, designed to secure both direct integrations and third-party applications. The choice of authentication method depends on the integration type and the level of access required. For server-to-server communication where an application needs full access to an Intercom workspace, API keys are typically used. For applications that interact with Intercom on behalf of users or require specific, limited permissions, OAuth 2.0 is the standard. Additionally, Intercom secures webhook payloads to ensure the integrity and authenticity of incoming data.

Developers working with Intercom can consult the Intercom API Reference for detailed information on endpoints and authentication requirements for specific operations. The platform offers documentation covering various aspects of its use, including developer-focused guides.

Supported authentication methods

Intercom supports several authentication mechanisms to accommodate different integration scenarios, each with specific use cases and security considerations.

API Keys

API keys are unique identifiers used to authenticate requests made to the Intercom API. They grant access to an entire Intercom workspace and are suitable for server-side applications, internal tools, or backend services that require broad programmatic access. API keys are typically long-lived and should be treated as sensitive credentials, similar to a password.

OAuth 2.0

OAuth 2.0 is an authorization framework that allows third-party applications to obtain limited access to an Intercom workspace on behalf of a user, without exposing their credentials. This method is preferred for public applications, integrations that require user consent, or when granular control over permissions is necessary. OAuth 2.0 involves a flow where a user grants permission for an application to access their Intercom data, resulting in an access token that the application uses for subsequent API calls. The OAuth 2.0 specification outlines the various grant types and flows.

Webhooks with Shared Secret

Webhooks enable Intercom to send real-time notifications to an external application when specific events occur within an Intercom workspace. To ensure the authenticity and integrity of these notifications, Intercom signs webhook payloads using a shared secret. The receiving application can then verify this signature using the same secret, confirming that the payload originated from Intercom and has not been tampered with. This mechanism is a common practice for securing webhook communications, as detailed in various security recommendations for webhooks.

Summary of Authentication Methods

Getting your credentials

Accessing the Intercom API requires obtaining the appropriate credentials for your chosen authentication method.

API Key Setup

1. Log in to your Intercom workspace.
2. Navigate to Settings > Developers > Developer Hub.
3. Select Your apps and then choose the app you are configuring or create a new one.
4. Within the app settings, you can find your API key (often labeled as a 'Personal Access Token' or similar).
5. Copy the API key securely. It will be used in the Authorization header of your API requests.

For detailed steps, refer to the Intercom Help Center documentation on API access.

OAuth 2.0 Setup

To use OAuth 2.0, you must register your application with Intercom and configure redirect URIs.

1. Log in to your Intercom workspace.
2. Go to Settings > Developers > Developer Hub.
3. Create a new app or select an existing one.
4. Configure the OAuth Settings for your app, including the Redirect URIs, which are the URLs where Intercom will send the user after they authorize your application.
5. Intercom will provide you with a Client ID and Client Secret. These are crucial for initiating the OAuth flow.
6. Implement the OAuth 2.0 authorization flow in your application, starting with directing users to Intercom's authorization endpoint, handling the callback with the authorization code, and exchanging it for an access token and refresh token.

The Intercom API reference provides specific OAuth 2.0 flow details and endpoint URLs.

Webhook Shared Secret Setup

1. In your Intercom workspace, navigate to Settings > Developers > Developer Hub.
2. Select your app and go to the Webhooks section.
3. Add a new webhook endpoint and specify the URL where your application will receive webhook events.
4. Intercom will generate a shared secret for this webhook. Copy this secret.
5. In your application, store this secret securely and use it to verify the signature of incoming webhook payloads from Intercom.

Authenticated request example

This example demonstrates how to make an authenticated request to the Intercom API using an API key. For OAuth 2.0, the process is similar, but the YOUR_API_KEY would be replaced with an OAuth access token.

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

In this cURL example:

• -X GET specifies the HTTP method.
• 'https://api.intercom.io/users' is the API endpoint to retrieve user data.
• -H 'Authorization: Bearer YOUR_API_KEY' is the header that carries your API key. Replace YOUR_API_KEY with your actual Intercom API key. The Bearer prefix is standard for token-based authentication.
• -H 'Accept: application/json' indicates that the client expects a JSON response.

When using OAuth 2.0, the YOUR_API_KEY would be an access token obtained through the OAuth flow. SDKs for Intercom's supported languages (JavaScript, React Native, iOS, Android, Ruby, Python, Node.js, PHP, Go, Java) typically abstract these details, allowing developers to configure the API key or token directly within the SDK client.

Security best practices

Adhering to security best practices is critical when integrating with Intercom to protect sensitive customer data and maintain the integrity of your applications.

Credential Management

• Do not hardcode credentials: Never embed API keys, client secrets, or webhook secrets directly into your source code. Use environment variables, configuration files, or secret management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault) to store and retrieve credentials securely.
• Rotate credentials regularly: Periodically change your API keys and client secrets. This reduces the risk if a credential is compromised without your knowledge.
• Limit access: Grant only the necessary permissions to your API keys or OAuth applications. Follow the principle of least privilege. For OAuth, request only the scopes your application absolutely needs.
• Secure storage: Ensure that any stored credentials, including refresh tokens, are encrypted at rest and protected from unauthorized access.

API Key Security

• Server-side use only: API keys should only be used in server-side code or secure backend environments. Exposing an API key in client-side code (e.g., JavaScript in a web browser, mobile app bundles) makes it vulnerable to extraction and misuse.
• IP Whitelisting: If Intercom supports it, restrict API key usage to a specific set of IP addresses belonging to your servers. This adds an extra layer of security, ensuring only authorized servers can use the key.

OAuth 2.0 Security

• Use HTTPS: Always use HTTPS for all communication involving OAuth flows, redirect URIs, and API calls to prevent man-in-the-middle attacks.
• Validate Redirect URIs: Configure strict redirect URIs in your Intercom app settings to prevent malicious redirects.
• Secure Client Secret: Treat your OAuth client secret with the same care as an API key. It should never be exposed client-side.
• Handle Tokens Securely: Store access and refresh tokens securely. Access tokens are typically short-lived, while refresh tokens, used to obtain new access tokens, should be stored with strong encryption and rotated.

Webhook Security

• Verify Signatures: Always verify the signature of incoming webhook payloads using the shared secret. This confirms the payload's origin and integrity. Reject any requests with invalid signatures.
• Use HTTPS for Webhook Endpoints: Ensure your webhook receiving endpoint uses HTTPS to encrypt data in transit.
• Implement Idempotency: Design your webhook handler to be idempotent. This means that processing the same webhook event multiple times will produce the same result, preventing issues if Intercom sends duplicate events.
• Rate Limiting and Monitoring: Implement rate limiting on your webhook endpoint and monitor for suspicious activity that might indicate an attack or misuse.

General Security Practices

• Error Handling: Implement robust error handling without exposing sensitive information in error messages.
• Logging and Monitoring: Log API access and webhook events, and set up monitoring to detect unusual activity or potential security incidents.
• Keep Dependencies Updated: Regularly update your application's libraries, frameworks, and SDKs to patch known vulnerabilities.
• Regular Security Audits: Conduct regular security audits and penetration testing of your applications that integrate with Intercom.