Let users sign in to your product using Slack.
It's fast, simple, and secure
Sign in with Slack extends our existing OAuth 2.0 application approval flow to simplify logging in users to your website, service, or application.
Use your favorite library or build it yourself; logging users in is just a few simple HTTP requests away.
Our new identity permission scopes and users.identity provide you everything needed to quickly identify team members signing in.
Slack Apps requesting only the identity family of scopes do not contribute to the maximum number of integrations that free teams may install.
Team administrators may configure whether Sign in with Slack is available to their team members, separately from any application installation restrictions already in place.
Guest accounts can not use Sign in with Slack.
Sign in with Slack is optimized for logging in. Returning users won't be distracted by unnecessary approvals, we'll send them back to your site, service, or app as fast as we can!
Take five minutes to set up your Sign in with Slack button. It complements your existing Add to Slack button, and you can always ask for additional permissions later. Find out how the two flows differ.
If this is your first time working with OAuth 2.0, Sign in with Slack is a simple way to get acquainted.
If you've already built an Add to Slack button, it should only take a few minutes to start signing users in with Sign in with Slack.
slack.com/oauth/authorize?client_id=CLIENT_ID&scope=identity.basic
code parametercode for an access token using slack.com/api/oauth.accessslack.com/api/users.identity?token=awarded_tokenOn the user's first login, we'll ask them to approve your app to access their user and basic team information and then send them to your redirect URL to complete sign in.
On subsequent logins, we'll skip the approval process and send the user back to your redirect as quickly as the tubes allow!
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 teams to "install," you'll still need to create a Slack App record.
After saving your application record, you'll find a panel detailing your Client ID, Client Secret, and Redirect URI configuration:
Save your client ID and secret in a safe, secure place. You'll need both later in this process.
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.
Point your buttons to https://slack.com/oauth/authorize and include a 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/authorize?scope=identity.basic&client_id=your_client_id"><img src="https://api.slack.com/img/sign_in_with_slack.png" /></a>
Use our button generator to make this even simpler.
| Parameter | Required? | Purpose & Examples |
|---|---|---|
scope |
Required |
A comma-separated list of permissions you're requesting the user to approve. If you're just logging users in, set this to Examples:
Important: To ask for additional permission scopes, you must use the Add to Slack flow instead. |
client_id |
Required |
Example:
|
redirect_uri |
Optional |
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. Examples:
http://localhost:3000/slack/auth/redirect and https://yourapp.com/slack/auth/redirect
|
state |
Optional |
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. Examples:
|
Once you have your hand-crafted button and redirect URI ready, it's time to focus on the process itself.
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.
If the user has never signed in to your product before, they'll 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)
If the user is simply signing in to resume an existing relationship with your Slack app, we'll send them to your redirect URL right away.
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.
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.
We'll now complete the OAuth negotiation sequence by building a request to oauth.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 appclient_secret - also issued when you created your appcode - that code parameter we just told you aboutredirect_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.access like:
GET https://slack.com/api/oauth.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,
"access_token": "xoxp-1111827399-16111519414-20367011469-5f89a31i07",
"scope": "identity.basic",
"team_id": "T0G9PQBBK"
}
See the oauth.access documentation for details on error conditions.
ok tells you whether the request completed successfully. Always look for a true value here before proceeding.access_token is the string you've been awarded to represent this userscope contains a comma-separated list of the scopes you've been awarded for this user. 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.team_id provides you the user's team ID.The values will be more useful to you when obtaining information about the user in the next step.
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.
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.
Now that you've negotiated your token, use it to make requests with the API.
Introducing the users.identity API method, available at https://slack.com/api/users.identity and 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 to https://slack.com/api/users.identity?token=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 give their username and unique IDteam and team_id give you their team name and unique IDTo 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.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 addressidentity.team - request access to the user's team nameidentity.avatar - request access to the user's profile image/avatarImportant: 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 are triumphantly victorious. The user token is yours and you've identified the user. Time for your application to do its thing.
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 a HTTP POST to https://slack.com/api/auth.revoke?token=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 this generator to help you build your OAuth authorization URL and display the Sign in with Slack button.
There are many ways to use Sign in with Slack. Here are some of our favorites.
Your Slack app may be part of a larger service, with its own notion of user accounts and identity.
Sign in with Slack makes it easy to associate a team member to 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.
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.
Use Sign in with Slack to make it easier for your potential customers to request more information about your products or services.
If you already have a Slack app, you've been using the same /oauth/authorize method used by Sign in with Slack to negotiate OAuth scopes like bot and incoming-webhook.
After receiving a token, apps typically request the auth.test method to confirm the installing user.
Tokens awarded with Sign in with Slack are instead used with the users.identity method for context on the user logging in to a site, app, or service.
Many apps previously used the identify permission scope to verify a user's identity. Some apps may have used in the users:read scope to retrieve extended information about users. In most cases, we recommend using this new Sign in with Slack flow instead.
The Add to Slack flow is intended for users to install applications and approve them for access in interacting with or retrieving information about their team.
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 (Retina, 344px by 80px)
The OAuth 2.0 authorization sequence is simple enough to implement 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.
