Using token rotation

This guide covers token rotation for Slack apps, which use granular permissions. You'll learn how to exchange your access token for a refresh token and an expiring access token.

With token rotation, you'll provide an extra layer of security for your access tokens.

Overview​

An access token represents an installation of your Slack app. Without token rotation, the access token never expires. With token rotation, it expires every 12 hours.

An OAuth flow with token rotation involves exchanging one expiring access token for a new one, using an additional token: the refresh token. The refresh token is then revoked, and a new refresh token is used to exchange the new expiring access token when it expires.

New access and refresh tokens need to be rotated in throughout the lifespan of the app for it to continue to function.

Before you begin​

If you don't have a Slack app already, that's okay! Click on the button below to begin the process of creating one:

Create an app

Fill out your App Name and select the Development Workspace where you'll play around and build your app. Don't fuss too much over either field—no matter what workspace you select, you'll still be able to distribute your app to other workspaces if you choose.

If you've just made your app, or if your Slack app isn't set up with our new OAuth V2, head over to our guide on Installing with OAuth. We'll wait right here for you.

Consider the Bolt SDKs​

If you use Bolt to develop your app, your job will be a whole lot easier. Token rotation is automatically handled in the Bolt frameworks for building Slack apps. All flavors of Bolt have versions that support token rotation.

Whether you're using an SDK or not, continue to turn on token rotation.

Turn on token rotation​

Before you turn on token rotation, consider how you're going to test your implementation. You don't want all your access tokens to expire before you've successfully figured out how to refresh them.

If your app is not published in the Slack Marketplace, token rotation is enabled via the OAuth & Permissions section of your app settings.

If your app is published in the Slack Marketplace, now is a good time to follow the advice in our guide to testing Slack Marketplace apps. Apps published in the Slack Marketplace can have token rotation enabled via the Published App Settings section of your app settings.

And if you're using a Bolt app, this is your stop! You're all good to go. If not, keep reading. The next section is just for you.

Exchange the long-lived access token​

A Slack app implemented with OAuth will already have a long-lived access token. You need to call the oauth.v2.exchange method to exchange that long-lived access token for a refresh token and an expiring access token.

You'll need your app's client_id and client_secret as well, which can be found under "App Credentials" within the specific app's "Basic Information" page.

Here's a sample call:

POST /api/oauth.v2.exchange
HOST slack.com
Content-Type: application/x-www-form-urlencoded

client_id=60503450.61416
client_secret=8bc5fc53901afc11c
token=xoxb-1234-...

Either a granular bot token or user token may be exchanged for a refresh token and expiring access token. You won't be able to exchange the same access token for a refresh token more than once.

After you refresh your short-lived credentials for the first time, we'll expire your original long-lived access token. Please don't try to revoke it yourself using auth.revoke, or you'll end up making the user redo the whole OAuth installation process (yikes!). Instead, just call auth.test to make sure the original token won't work anymore. Keep in mind that this applies to both user and bot tokens, so make sure to repeat the OAuth process to get your hands on fresh credentials.

Here's a sample response from oauth.v2.exchange when exchanging a bot token:

{
    "ok": true,
    "access_token": "xoxe.xoxb-1-...", // New access token
    "expires_in": 43200, // 12 hours
    "refresh_token": "xoxe-1-...", // New refresh token
    "token_type": "bot",
    "scope": "commands,incoming-webhook",
    "bot_user_id": "U123456",
    "app_id": "A123456",
    "team": {
        "name": "Slack Softball Team",
        "id": "T123456"
    },
    "enterprise": {
        "name": "slack-sports",
        "id": "E12345678"
    },
}

Notice that your access_token now has a new xoxe. prefix. The access token's lifespan is based on the expires_in field. This field defines the number of seconds until the access token you've received expires. It will always expire in 43,200 seconds, which is 12 hours.

The response will also have a refresh_token.

You now have your first set of rotatable tokens!

Refresh a token