How to Upgrade Your Slack OAuth Scopes

Duretti Hirpa
Dec 18, 2015 · 5 min read
Image for post
Image for post
Partner, let me upgrade you

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?

Image for post
Image for post
No developer left behind, fam

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.

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)!

Navigate to application page, located at http://api.slack.com/applications

Image for post
Image for post

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:

Image for post
Image for post

Clicking “Update Tokens” will officially start the migration.

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.

Image for post
Image for post

Once you’re satisfied with the new scopes, go ahead and hit the “Continue” button

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”).

Image for post
Image for post

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?

Image for post
Image for post

Once you’ve updated your code, go ahead and hit that “I’ve Updated My App” button.

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.

Image for post
Image for post

Provided you’re happy with the summary we’re showing, go head and start your migration by clicking on “Start Migration”.

Image for post
Image for post

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.

Image for post
Image for post

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.

Image for post
Image for post

Once you receive a ping from Slackbot, you’ve successfully upgraded your tokens. Nice.

Image for post
Image for post

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.

Slack Platform Blog

Several bots are typing…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store