Upcoming deprecation of API Keys
--
July 2016 — this post originally featured on our previous blog at developers.intercom.io
Today marks the start of the gradual deprecation of API Keys as we move towards OAuth and Personal Access Tokens becoming our only methods for authorization.
In the past, API Keys have been the primary method to authorize your integration with Intercom but — whilst they’ve served us well as a quick method up until now — we’ve been moving towards using OAuth instead as it provides a much better experience for users.
Note: Personal Access Tokens available for those accessing their own data only
We’re introducing Personal Access Tokens instead of OAuth for those of you who just want to access your own Intercom data through the API. Read on for more detail, or click here for the setup guide.
Not only does OAuth do away with the fiddly copy and pasting required for API Keys, but it also provides users more security and control over how their data is being used. This reduction in friction in turn means more users for you; our data shows that apps using OAuth enjoy twice as many signups as those using API Keys.
We introduced OAuth as an alternative to API Keys earlier this year and have been thrilled to see so many of you already start to use it in your integrations. Now, we’re moving towards deprecating API Keys fully so all integrations are using either OAuth, or Personal Access tokens where you’re only accessing your own Intercom data.
“Since switching our Intercom integration to OAuth more of our users have been able to set up their authentication without any of our team having to walk them through it. This has reduced our workload, sped up our user onboarding, and decreased the drop-off rate; essentially it has been a pretty easy win for us.” — Max Dupenois, Developer at Driftrock
We understand that this change will mean some work for developers, but believe it is ultimately the best thing for our users. To help with the migration, we’re making improvements to OAuth, as well as providing lots of useful guides about switching — read on for more details.
Key dates for API Key deprecation
The deprecation of API Keys means that all apps will need to start using OAuth or Personal Access Tokens (click here if you’re unsure which you need) in order to continue accessing data within Intercom through the API.
We want to give you plenty of time to migrate, so we’ve put together a timeline to help you plan:
- Today (19th July) — Announcement, no immediate changes to API Keys
- 9 Sept 2016 — users will no longer be able to generate new API Keys, so you’ll need to start using Personal Access Tokens instead — or, for public integrations, have OAuth in place in order to allow new users to authorize your service
- Jan 27th 2017 –** API Keys will no longer be accepted as a method for authorizing, so you’ll need either a Personal Access Token or OAuth to replace them — for public integrations, any existing users you have will need to be migrated to OAuth by this date to continue using your integration
We’ll be posting reminders when each of these key dates comes round (so keep an eye on this blog!), but we recommend migrating as soon as possible to ensure you don’t experience any disruption. Throughout the coming weeks we’ll also be making further improvements to OAuth to make it even easier to use.
Note: For those building custom integrations that only access your own companies’ data, you can migrate to using Personal Access Tokens rather than OAuth. Personal Access Tokens are simple and easy to setup, and can be created instantly — here’s a setup guide.
Migrating to OAuth
We want to make migrating to OAuth as easy as possible for you, so in advance of the deprecation we’ve been working hard to make OAuth better to use. We’ve already made updates such as improving stability and giving you more control over your app permissions, and over the coming weeks you’ll see more changes as we make the application process smoother.
We’ve also put together some guides to help you make the switch:
Of course, we’re also on hand if you have any problems or questions — just send us a message if you need any help.
Remember to also update any setup documentation you have for users to reflect the new flow once you’ve implemented OAuth.
Migrating to Personal Access Tokens
If you’re using the API to only access your own Intercom data (rather than other companies’ data) — for example, if you’ve built an integration or workflows for your company to use internally — you’ll still need to switch from using API Keys, but you can use a Personal Access Token rather than OAuth, which is simpler and quicker to set up.
Personal Access Tokens can also be useful for prototyping or getting started quickly when building other types of integrations, but you’ll need to move to OAuth as soon as you want to start accessing other users’ data.
Personal Access Tokens are simple and easy to setup, and can be created instantly — here’s a setup guide.
Interested in building on the Intercom platform? Check out our Developer Hub to get started.
