Docs
Tutorials
Developer Program
Your apps

Legacy: Sign in with Slack

This article describes an outdated approach to Sign in with Slack. The modern Sign in with Slack builds on the OpenID Connect protocol, allowing a more familiar and flexible sign in flow. Check out the modern Sign in with Slack flow now.

New Sign in with Slack apps using this outdated protocol may no longer be created after July 22, 2021.

Sign in with Slack extends our existing OAuth 2.0 application approval flow to simplify logging in users to your website, service, or application.

  • It's understandable for users.
  • It's secure. Slack interfaces with SSO providers and handles two-factor authentication so you have less to worry about.

Use your favorite library or build it yourself; logging users in is a few HTTP requests away.

Sign in with Slack approval process screenshot

Things to keep in mind before you begin

Sign in with Slack is a specific feature available to Slack apps.

Your app uses the Slack OAuth 2.0 flow to negotiate limited permissions from a Slack user.

Overview

Here's what your app receives from the Sign in with Slack dance:

  • Access to basic information about a user who goes through the OAuth flow—an ID and a name.
  • Optionally, with more scopes that you request and the user grants, you receive a few more pieces of information like the user's email address and their avatar in Slack.

Here's what a user gains from using Sign in with Slack:

  • The simplicity of signing in only to Slack, rather than signing into many additional apps
  • The confidence that Slack account security is maintained

Sign in with Slack can benefit both your app and your users. Keep in mind that there are limitations as well, though.

Everybody can sign in with Slack. Here are the exceptions.

Workspace administrators may configure whether Sign in with Slack is available to their members, separately from any application installation restrictions already in place.

Guest accounts can not use Sign in with Slack.

Slack users with an anonymized Apple relay email address (for example, if a user signs into Slack via Apple) may not use Sign in with Slack.

Implementation Overview

Negotiating tokens with Slack's OAuth 2.0 authorization flow

Token negotiation flow

  1. User arrives at your site and clicks Sign in with Slack button
  2. User arrives at slack.com/oauth/v2/authorize?client_id=CLIENT_ID&user_scope=identity.basic and briefly approves sign in
  3. User arrives at your specified redirect URL with a code parameter
  4. Your server exchanges code for an access token using slack.com/api/oauth.v2.access
  5. Your server uses the resultant access token to request user & workspace details with slack.com/api/users.identity, passing the awarded token as a HTTP authorization header or POST parameter

On the user's first login, we'll ask them to approve your app to access their user and basic workspace information and then send them to your redirect URL to complete sign in.

On subsequent logins, we'll provide an accelerated version of the approval process, still requiring a click, and then send the user back to your redirect.

  • Already have a Slack app and redirect URL? Skip ahead.

Details

Create your Slack app if you haven't already

You'll need credentials to use Sign in with Slack. To retrieve your Client ID and secret, you'll need to create a Slack App if you haven't already.

Even if you're just implementing Sign in with Slack and don't have a Slack App for workspaces to "install," you'll still need to create a Slack App record.

Create a Slack app now

Prepare your redirect URI

After saving your application record, you'll find a panel detailing your Client ID, Client Secret, and Redirect URI configuration:

OAuth redirect configuration

Save your client ID and secret in a safe, secure place. You'll need both later in this process.

What's a redirect URL?

Redirect URLs are specific URLs on your site or application that handle a crucial part of the authentication flow. By registering your redirect URLs as part of your application record, you're instructing Slack the valid locations to send authorization codes.

When a user lands on your redirect URL with an authorization code, you'll then perform server-side operations to exchange the authorization code for a bearer token, representing the user's approval of your product or application.

As you develop, you can specify redirects on localhost but we recommend using a publicly available server supporting SSL once your integration is user-facing.

Once you've decided where in your application you'll be sending users, provide it on this configuration screen and save your work.

Set up your Sign in with Slack Button

Point your buttons to https://slack.com/oauth/v2/authorize and include a user_scope parameter set only to identity.basic (and potentially related scopes we'll discuss soon), along with your client_id.

If your application record contains multiple redirect URLs, specify the one you want to use as the redirect_uri parameter.

<a href="https://slack.com/oauth/v2/authorize?user_scope=identity.basic&client_id=your_client_id"><img src="https://api.slack.com/img/sign_in_with_slack.png" /></a>

Valid parameters

Parameter Purpose Examples Required?
user_scope A comma- or space-separated list of permissions you're requesting the user to approve. If you're just logging users in, set this to identity.basic. You can't ask for identity.email, identity.team, or identity.avatar without also asking for identity.basic. To ask for additional permission scopes, you must use the Add to Slack flow instead. identity.basic

identity.basic identity.email

identity.basic identity.team identity.avatar		 Yes
client_id The unique identifier of the client. 1048553852.9553671552 Yes
redirect_uri The URL the user should return to once Slack has validated their approval. Must be URL-encoded as per RFC 3986 and correspond to a registered URL associated with your application record. http%3A%2F%2Flocalhost%3A3000%2Fslack%2Fauth%2Fredirect

https%3A%2F%2Fyourapp.com%2Fslack%2Fauth%2Fredirect

Note that these are the URL-encoded versions of http://localhost:3000/slack/auth/redirect and https://yourapp.com/slack/auth/redirect		 No
state An optional string of characters you've generated to maintain state. If specified, Slack will send this value back to your redirect URI along with the user. This value is frequently used to validate that your application initiated the login sequence. It is best to use a non-human-readable value. aabbCCddeeFF

resumeSignIn		 No
team ID of a workspace to attempt to restrict the login to. When a valid workspace ID is passed to team and the authenticating user is already signed in to that workspace, passing this parameter ensures the user will auth against that workspace. If the user is not signed in yet, the user will be asked to specify a workspace to sign in to. That workspace will then be used as they complete the authorization flow, regardless of any team parameter you provided when the flow began. No

Once you have your hand-crafted button and redirect URI ready, it's time to focus on the process itself.

Authorization

After a user clicks your Sign in with Slack button, their web browser should arrive on Slack's servers.

Your application will wait patiently while the user handles some business or Slack just sends them on their way back to your redirect URL.

The user will be prompted to approve your Slack app.

If a user decides not to perform Sign in with Slack, they'll be redirected to your redirect_uri where you may also receive an error parameter. (See OAuth docs)

Either way, your next steps are the same.

The game is afoot. The user's browser has redirected them to your specified redirect URL. It's time for your application to stop waiting and do something again.

Interpret parameters

When your redirect URI was triggered, Slack includes a fresh code parameter, along with any state parameter you had affixed to your sign in URL.

The code parameter is an authorization code that you will exchange for a long-lived access token. It can only be exchanged once and you only have ten minutes to exchange it.

If you're using a state parameter, you'll want to verify that the state matches your expectations. If it doesn't, display an error message and do not attempt the next steps.

Obtain an access token

We'll now complete the OAuth negotiation sequence by building a request to oauth.v2.access.

Use the code parameter you just received in conjunction with your secure client secret and client ID to prepare your request parameters:

  • client_id - the client ID issued when you created your app
  • client_secret - also issued when you created your app
  • code - that code parameter we just told you about
  • redirect_uri - only include this if you've explicitly specified it in your Sign in with Slack button. When provided, it must match exactly, though properly URL-encoded.

We'll then take those parameters and perform a HTTP GET to https://slack.com/api/oauth.v2.access like:

GET https://slack.com/api/oauth.v2.access?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=XXYYZZ

In response, you'll receive an application/json payload containing your access token.

{
    "ok": true,
    "app_id": "A0118NQPZZC",
    "authed_user": {
        "id": "U065VRX1T0",
        "scope": "identity.basic,identity.email,identity.avatar,identity.team",
        "access_token": "xoxp-yoda-yoda-yoda",
        "token_type": "user"
    },
    "team": {
        "id": "T024BE7LD"
    },
    "enterprise": null,
    "is_enterprise_install": false
}

See the oauth.v2.access documentation for details on error conditions.

Response breakdown

Here's a breakdown of oauth.v2.access's typical response for Slack apps.

  • ok tells you whether the request completed successfully. Always look for a true value here before proceeding.
  • app_id echoes back the ID for your Slack app.
  • authed_user is an object about the user who just authorized your application for sign in. It contains the token!
    • id is the user's ID.
    • scope are the comma-separated user scopes the user granted you, in this case the identity.* scopes you asked for.
    • access_token is the token you can use to call Sign in with Slack identity methods.
    • token_type is always user for Sign in with Slack.
  • team will include a single field called id for the workspace ID
  • enterprise will populate with an id field when the workspace belongs to an Enterprise Grid.
  • is_enterprise_install will be true when the workspace is part of an Enterprise Grid.

If you're using Sign in with Slack for more than just sign in, the list of scopes may include other scopes you've requested and received for this user. See Appending Scopes for more information. But beware, you can't ask for Sign in with Slack scopes at the same time as other scopes.

The values will be more useful to you when obtaining information about the user in the next step.

Storing identity access tokens

If you'll be saving your identity tokens for later, you'll want to securely store them adjacent to both a user's ID and team ID. Consider these three pieces of information a triad.

You've authenticated a specific user represented by user_id, within a specific team represented by team_id, and that authentication is symbolized by the access_token you've been awarded.

Be careful not to distribute access tokens (or your client secret) in public code repositories or other unsecured locations. Read our article on safely storing credentials.

Using Sign in with Slack and Add to Slack together

If the user logging in with Sign in with Slack has previously approved your application for other scopes using Add to Slack, then the resultant access tokens will contain both the identity.* scopes you used for sign in and any scopes you asked for when using Add to Slack. To ask for permissions beyond identity.*, request them with the Add to Slack flow.

Using tokens to retrieve user and team information

Now that you've negotiated your token, use it to make requests with the API.

You'll call the users.identity API method, requiring the identity.basic scope—this method is the primary means to identify users.

If the bearer token you received in the above step was xoxp-1111827393-16111519414-20367011469-5f89a31i07, you'd send your request like:

GET https://slack.com/api/users.identity
Authorization: Bearer xoxp-1111827393-16111519414-20367011469-5f89a31i07

The response will be in JSON and contain a few fields you'll want to look out for:

{
  "ok": true,
  "user": {
    "name": "Sonny Whether",
    "id": "U0G9QF9C6"
  },
  "team": {
    "id": "T0G9PQBBK"
  }
}
  • ok tells you whether the request completed successfully. Always look for a true value here before proceeding.
  • user and user_id gives you the user’s real name and unique user ID
  • team and team_id gives you their team name and unique ID

To retrieve additional information about the team member, such as their email address, team name, or image avatar, you'll need to request additional scopes during the authorization phase.

With those scopes approved, the response for users.identity will be modified to include the associated data, such that your response may look like:

{
  "ok": true,
  "user": {
    "name": "Sonny Whether",
    "id": "U0G9QF9C6",
    "email": "sonny@captain-fabian.com",
    "image_24": "https://secure.gravatar.com/avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg?s=24&d=https%3A%2F%2Fdev.slack.com%2Fimg%2Favatars%2Fava_0010-24.v1441146555.png",
    "image_32": "https://secure.gravatar.com/avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg?s=32&d=https%3A%2F%2Fdev.slack.com%2Fimg%2Favatars%2Fava_0010-32.v1441146555.png",
    "image_48": "https://secure.gravatar.com/avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg?s=48&d=https%3A%2F%2Fdev.slack.com%2Fimg%2Favatars%2Fava_0010-48.v1441146555.png",
    "image_72": "https://secure.gravatar.com/avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg?s=72&d=https%3A%2F%2Fdev.slack.com%2Fimg%2Favatars%2Fava_0010-72.v1441146555.png",
    "image_192": "https://secure.gravatar.com/avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg?s=192&d=https%3A%2F%2Fdev.slack.com%2Fimg%2Favatars%2Fava_0010-192.v1443724322.png",
    "image_512": "https://secure.gravatar.com/avatar/e3b51ca72dee4ef87916ae2b9240df50.jpg?s=512&d=https%3A%2F%2Fdev.slack.com%2Fimg%2Favatars%2Fava_0010-512.v1443724322.png"
  },
  "team": {
    "id": "T0G9PQBBK",
    "name": "Captain Fabian's Naval Supply"
  }
}

Identity Scopes

  • identity.basic - request access to basic information about the user and use Sign in with Slack to log them in. You must request this scope in order to request any of the scopes below.
  • identity.email - request access to the user's email address
  • identity.team - request access to the user's team name
  • identity.avatar - request access to the user's profile image/avatar

Important: Use these scopes and Sign in with Slack only when you're logging users into your application or site. Use the Add to Slack flow when asking teams to approve your Slack App using non-identity.* scopes.

You're done!

Time for your application to do its thing.

Revoking tokens

Sign in with Slack access tokens do not automatically expire. Users can revoke tokens at any time, and so can you:

If you're off-boarding a user or otherwise wish to revoke a token during your development process, use the new auth.revoke API method. The token you specify as the token URL parameter will be revoked.

For example, issuing an HTTP POST to https://slack.com/api/auth.revoke with the token POST parameter set to xoxp-2323827393-16111519414-20367011469-5f89a31i07 would give you this response:

{
  "ok": true,
  "revoked": true
}

After execution, the specified token will no longer be functional for API requests.

Use cases

There are many ways to use Sign in with Slack. Here are some of our favorites.

Binding Slack team members to service accounts

Your Slack app may be part of a larger service, with its own notion of user accounts and identity.

Sign in with Slack can be used to associate a team member with a specific account in your service.

If your app is interacting with an unrecognized user via a bot user or slash command, you can send the user a message containing an authorization URL requesting identity-related scopes, or a link to a page on your site that presents a Sign in with Slack button.

Confirming identity for internal projects

Many teams use custom integrations or team-focused Slack apps to work with internal services and applications. Use Sign in with Slack to confirm your organization's team members and log users in to your team's content.

Business inquiries

Use Sign in with Slack to make it easier for your potential customers to request more information about your products or services.

Helpful resources

How is Sign in with Slack different from Add to Slack?

Using Sign in with Slack makes your app a specific type of Slack app. Sign in with Slack allows you to use the users.identity method for context on the user logging in to your app or service. You can think of Sign in with Slack as a very particular feature, an exact tool for an exact job—to gain basic information about users for the purpose of onboarding them to your app or service .

The Add to Slack flow, in contrast, is much more generally applicable. It's intended for users to install an app to Slack. It can be used with any app. Most of the time, if your app is doing something beyond gaining basic information about a user to power your service, it should not use Sign in with Slack. It can, however, use the Add to Slack flow.

Assets

Please use these assets when presenting team members the opportunity to use Sign in with Slack.

This HTML snippet references our CDN-hosted buttons:

<img src="https://platform.slack-edge.com/img/sign_in_with_slack.png" srcset="https://platform.slack-edge.com/img/sign_in_with_slack.png 1x, https://platform.slack-edge.com/img/sign_in_with_slack@2x.png 2x" />

Example rendering:

If you want to host the assets yourself, please download these images:

Download PNG (170px by 40px)

Download PNG (Retina, 344px by 80px)

Libraries

You can implement the OAuth 2.0 authorization sequence yourself but if you want to use an existing library, almost any supporting the authorization code grant flow should work well with Sign in with Slack.

While most existing OAuth 2.0 libraries should cooperate with Sign in with Slack, some libraries built to utilize the Add to Slack button may need modifications to recognize these new scopes and the alternate users.identity method used to retrieve identification details after token negotiation.