How to Upgrade Your Slack OAuth Scopes
You might recall that the Platform team here at Slack recently released updates to our OAuth scopes –and with it, we added a veritable slew of new scopes. These scopes are more granular and let you choose exactly the level of access you need. This is great! However, we got to thinking, and realized: to take full advantage of the updates to the scopes, you’d have to be creating new applications! What about applications and developers that have been with us from day one?
The Upgrade Path
With this in mind, we started work on a migration tool that would take our existing, broader scopes (client, post, read, and identify) and transmogrify them into our new and improved scopes. By upgrading to our new scopes, not only will existing developers have more control over their applications, but it’s a fantastic step towards making building on top of Slack more secure.
Alright, I’d Subscribe to Your Newsletter
We’ve just covered the why, let’s get into the how.
To kick off the upgrade, there’s a few things to note. You’ll:
- need to be the developer that registered the application initially
- be familiar with your application — it does require modifying your application’s code
- set aside a bit of time, to both walk through the migration, as well as deploy updates to your application (yes, it’s so important we’re saying it twice).
- do great (we’re so pumped you’re upgrading)!
Prequel
Navigate to application page, located at http://api.slack.com/applications
You’ll notice some yellow text, letting you know that your application is ready to be migrated, and how many tokens would be migrated.
If you click on your application’s name, you can learn a bit more about migrating your tokens to use the new object scopes:
Clicking “Update Tokens” will officially start the migration.
Step One
The next page will allow you to pick the object scopes that you want to migrate to. We’ll make our very best educated guess, based on your recent usage patterns of the Slack API, but ultimately, you know your application better than we do.
Once you’re satisfied with the new scopes, go ahead and hit the “Continue” button
Step two
So, you’ve picked out your new scopes! Excellent. We’ll show you a summary of the tokens issued to your application (“legacy tokens”), and what you’ll be getting in return (“object scopes”).
OK, remember when we said you’ll have to update your code earlier? That part is happening now. You’ll need to pop into your application’s codebase, and update the Slack OAuth authentication URL (if you need a bit of a refresher on the OAuth authentication flow at Slack, you can check out our documentation listed here).
Now, we’ve provided a URL that should trigger the OAuth flow for you. You may need to split it up, depending on what your code looks like. Trust, but verify, you know?
Once you’ve updated your code, go ahead and hit that “I’ve Updated My App” button.
Step three
In the background, we’re looking to see that you’re using the new object scopes. Once we’ve detected that, we’ll show you a migration summary — it’ll be very similar to what you saw in Step Two.
Provided you’re happy with the summary we’re showing, go head and start your migration by clicking on “Start Migration”.
Wait. Why are you seeing a Clippy-esque dialog?! What kind of malarkey is this?
To be fair, we really want you to be sure that these are the scopes you want, because this is kind of a one-shot kind of thing.
Once you click “migrate my tokens”, we’ll kick off the upgrade migration.
Epilogue
Rad — your token migration is in progress. We’ll leave it to Slackbot to notify you once your migration is complete.
Once you receive a ping from Slackbot, you’ve successfully upgraded your tokens. Nice.
Go forth! Develop and prosper.
Now that your application is updated (and if it’s an application you want to share) why not submit it to Slack’s App Directory? You’re one step closer to being approved because you’re using the new scopes!
If you have questions, feedback, or high-fives, we’d love to hear them! You can find us on Twitter at http://twitter.com/slackAPI, or, you can send us email at feedback@slack.com.
