You must enable javascript in order to use the Slack API Documentation. You can do this in your browser settings.
Go to Slack

Hello World Slack OAuth

By Steve Hammond

Apps make Slack a more productive and enjoyable place to get work done. Let’s not also forget that super amazing features, like the Events API and message buttons, are exclusive to apps. If you want to create an app and install it on your team – but are new to Slack’s OAuth process – this tutorial is for you.

You will have a shiny new app installed on your team upon completing these three steps:

  1. Create your Slack app
  2. Setup the OAuth installation flow
  3. Install the app on your team

A Node.js app will be used as an example. If you prefer Python, Ruby, or another web-friendly language, you should be able to follow along and translate to your chosen language.

What you’ll need

  • Publicly accessible server running Node.js
  • Following Node.js modules:

    • Express: popular http framework
    • Request: simple http request client
    • Dotenv: loads environment variables from a .env file

    For example, the beginning of your server file should resemble:

    require('dotenv').config() 
    var express = require('express')
    var request = require('request')
    var app = express()
    

Our complete OAuth documentation is a good reference as you go through the tutorial.


Create your app

  1. Go to https://api.slack.com/apps and click the big green Create New App button. Enter a name for your app and click the next prominent green button.

  2. The Basic Information link on the left hand side of your app’s settings page contains information you’ll need, such as the Client ID and Client Secret, to authenticate OAuth requests for your app. Copy these to your .env file on your server. See docs here for variable format if you’re following the Node.js example.

  3. It’s time to setup a Redirect URL for your app. This is the endpoint for Slack to send a unique temporary code to your server during a user’s installation. Your server will then send back this code, along with your Client ID and Client Secret, so that we know we can trust you.

    The Redirect URL must be publicly accessible and secure. If you want to run your server locally, e.g. on localhost, Ngrok is a service that will create a tunnel to your local or private endpoint.

    Here’s a quick ngrok tutorial to get you up and running. 💯

    You can save your Redirect URL in the OAuth & Permissions section on the left. After you save your changes, you can always come back later and change them.

That’s it for your Slack app settings page. Now let's get your Node.js app configured for OAuth glory!


Setup OAuth installation flow

The Add to Slack button is an easy way to install the app. Navigate here, select your new app from the Code for app dropdown menu and tick your desired scopes from the list of incoming-webhook, commands, and bot. Now copy the HTML for the button to a file on your server. We'll call it add_to_slack.html.

Scopes are an integral part of OAuth as they define your app’s permissions to access API methods and bundled features, such as webhooks and slash commands. Browse the OAuth Scopes page to learn more.

Next, add a GET route to your server file for your basic, yet elegant, button:

app.get('/auth', (req, res) =>{
    res.sendFile(__dirname + '/add_to_slack.html')
})

Add Redirect URL route

When a user clicks your Add to Slack button, a request is sent to Slack’s servers. The Client ID sent via the button click is validated and a code is sent as a GET request to your Redirect URL. The code is in a JSON object named query of the request, i.e. req.query.code.

You server’s task is to receive this code and send it back along with the Client ID and Client Secret as parameters to the OAuth Access Token URL: https://slack.com/api/oauth.access

The response body of your request will contain the tokens, webhooks and IDs that your app can use to make its magic happen. Example response body:

{
    "ok":true,
    "access_token":"xoxp-...",
    "scope":"YOUR_SCOPES",
    "user_id":"U...",
    "team_name":"TEAM_NAME",
    "team_id":"TEAM_ID",
    "incoming_webhook": {
        "channel":"#general",
        "channel_id":"C...",
        "configuration_url":"https:\\/\\/my.slack.com\\/services\\/B...",
        "url":"https:\\/\\/hooks.slack.com\\/services\\/TEAM_ID\\/B...\\/..."
    }
}

See the following snippet to accomplish the receipt of the code to your Redirect URL, the GET request back to Slack and the response with your newly installed app’s credentials. Not too hard, hey?

app.get('/auth/redirect', (req, res) =>{
    var options = {
        uri: 'https://slack.com/api/oauth.access?code='
            +req.query.code+
            '&client_id='+process.env.CLIENT_ID+
            '&client_secret='+process.env.CLIENT_SECRET+
            '&redirect_uri='+process.env.REDIRECT_URI,
        method: 'GET'
    }
    request(options, (error, response, body) => {
        var JSONresponse = JSON.parse(body)
        if (!JSONresponse.ok){
            console.log(JSONresponse)
            res.send("Error encountered: \n"+JSON.stringify(JSONresponse)).status(200).end()
        }else{
            console.log(JSONresponse)
            res.send("Success!")
        }
    })
})

In the above example, console.log() is used to view the response body. In your code, you’ll want save the response object immediately in a safe and secure place. You only get one chance to save it!

Check out the Safely Storing Credentials page for best practices on how to handle this sensitive data.


Install the app on your team

Save your files, triple-check your code, and restart your server.

Now open your Add to Slack button page in your browser, click on the button and you should be navigated through the installation of your app!

If installed successfully, your app will be listed here: https://my.slack.com/apps/manage

Congratulations!

Related documentation