"API Token" in documentation too vague

[charlesreid1]

Description

A better variable name than "SLACK_API_TOKEN" should be used. This vague language is common to auth system documentation and makes it confusing and hard to understand. "API token" is too vague. Is that the BOT_TOKEN discussed here? The client ID/secret token? The consumer API token? A temporary access token that gives an application full permissions for my account, like Github provides, that I somehow generate...?

This tokens and authentication page mentions that you use test tokens in place of the API tokens. It then goes on to say, "Tester tokens are not intended to replace OAuth 2.0 tokens. Once your app is ready for users, replace this token with a proper OAuth token implementation." So, is the SLACK_API_TOKEN an OAuth token? Why would there only be one token, when OAuth gives you two (client ID and client secret)? Or is the test token something different from the API token?

I have a high level understanding of how OAuth works and have used it before, but I have no clue what Slack wants me to do because the terminology used in the documentation is not consistent.

Please tie this documentation to what a Slack user actually sees in their control panel, and where in in the control panel the Slack user can find these details.

What type of issue is this? (place an x in one of the [ ])

• [ ] bug
• [ ] enhancement (feature request)
• [ ] question
• [X] documentation related
• [ ] testing related
• [ ] discussion

Requirements (place an x in each of the [ ])

• [x] I've read and understood the Contributing guidelines and have done my best effort to follow them.
• [x] I've read and agree to the Code of Conduct.
• [x] I've searched for any related issues and avoided creating a duplicate issue.

---

Bug Report

(documentation fix)

[charlesreid1]

This link (Create and regenerate API tokens) also mentions:

• legacy tokens
• legacy custom integrations
• bot user tokens
• internal app tokens
• external app tokens

😕

[charlesreid1]

This SO post mentions a user access token and a bot token, both resulting from the OAuth process. I'm guessing this bot API token is the one you really want, although this is not in any way made clear. The documentation gives fragments of a Flask app to run the OAuth process, but nothing complete. Is this provided as a single downloadable script in a repository somewhere?

I also don't see a way to change the callback URL of an app that's already been created anywhere in the documentation (or in the app settings, for that matter).

Overall, this documentation is throroughly bewildering. OAuth is a confusing process to begin with; this documentation makes it impossible to get up and running without investing several hours. Huge headache, especially compared to how easy it is to get rolling with Twitter and Github OAuth steps and APIs.

[aoberoi]

@charlesreid1 i can empathize with some of the confusion you are having, and i'm making notes and delivering this feedback to the rest of the team responsible for documentation. thank you for your candor.

the bottom line: any of the tokens you mentioned in this comment are valid to use for SLACK_API_TOKEN. its actually generic on purpose, although that purpose is not clear and i'm sorry about that.

i'll spare you the history lesson, but as you can probably imagine, the Slack API wasn't born in a day, and over time we invented different types of authentication tokens for using the API. all of them are still valid for authenticating against the API, so any of them can be used with this library.

now, depending on what you are trying to specifically build utilizing this library, one token type might be more correct than others.

• user tokens (start with xoxp)- these are the base of what you get back from the OAuth process. when you request scopes during that process, you are asking to append those scopes onto this token. its called a user token because you're app will then behave in a perspectival manner from the installing user (although it has an identity of its own). the exception is...

• bot tokens (start with xoxb). these can also be obtained using the OAuth process, but the difference is that they are only present in the final response to oauth.access when you are requesting bot scope (this token lives inside the "bot" key of the response). bot is a special scope - its an aggregate of some special scopes that Slack has curated as appropriate for a Bot User. what's a Bot User? its a separate identity in the Slack team: it doesn't behave in the perspectival manner with the user tokens, it behaves as its own entity. you cannot append new scopes onto it. there are two "flavors" of bot users: app bots and custom bots. they differ slightly in which scopes Slack has curated into the aggregate, but otherwise they both look about the same (both start with xoxb). the difference is in how they are created. app bots are created as part of a Slack App, while custom bots are created outside of an app, as a custom integration. speaking of apps...

• internal and external app tokens (start with xoxa): apps are installable using OAuth and bundle many features of the platform into a single installation event. this differs from custom integrations which are one-off (a slash command, an incoming webhook, a bot user would all need to be installed separately). what this also does for your app is allows it to become distributable on the Slack App Directory, so that many workspaces can install the same app. this is great! originally, apps were given both user tokens and bot tokens for authentication (depending on which of those features were turned on). however the perspectival nature of user tokens in tandem with a sidecar bot token became a conceptual burden. the app token is a simplification that you can think of as all the powers of both combined. every app gets an identity that isn't bound to the user who installed it, and that identity can be granted the exact scopes you as a developer request. this style of app development is currently available in developer preview, which means the APIs might change before we call stamp it as stable. the distinction of internal versus external isn't a functional one: its just an acknowledgement that you can develop an app that is meant for only one workspace (internal) or meant to eventually be available to multiple workspaces (external).

• legacy tokens and tester tokens are almost always wrong. as a new developer you can safely ignore these. references to them stay in the docs because some people are still using them.

---

you didn't mention this, but you might also see "Verification Token". this token is meant for your app to be able to authenticate Slack (rather than Slack to authenticate your app). with some features (slash commands, interactive messages, events API), Slack is the one sending you the request. in those cases, you want to make sure its actually Slack that sent the request, so you check to make sure the verification token matches what it says in your app management page.

lastly, the client id and client secret are only used in the OAuth process to exchange a authorization code (grant) for an access token. this is the request to oauth.access. these are constant identifiers for your app across all workspaces where the app is installed, but never used for authentication using the APIs.

[pykenny]

For anyone who run into this article while stretching head on reading article like this: https://api.slack.com/apis/connections/socket#sdks

(Solved, see below) (Can anyone explain, why there are two tokens used in the code, when there's only one app token is mentioned and set up in previous context? If an app token is combination of user token and bot token, as the above comment says, then why do we need another bot token (apply bot token to original app + apply app token to socket adapter) in this example?)

• First, Slack has moved their article about token types over here, and token types have changed a bit currently.

• Also, there are more token types not covered in this article, such as xoxc, xoxo, and etc.. I guess they're fully deprecated so Slack decided to remove them from documentation:

• From the latest article and my understanding, most of the thing mentioned in the above comment still holds, while xoxa tokens are replaced with xapp tokens.

Update: Just saw the description of app token:

Special tokens used with specific APIs...

Now I think the difference between xoxa and xapp is that scopes granted to xapp is more restricted, so in the Socket Mode case, you'll still need a bot token to enable features like posting or reading channel history.

[pykenny]

Another perplexing part in the documentation is that now Slack offers signing secrets and claims to replace application tokens discussed in this thread with the new mechanism, while the other tutorials are still using the "old verification token"s to enable bots and applications.

~So what should I do now? Bolt's documentation keeps telling me to use the "to be deprecated" way for authentication! 🤷‍♂️~ (Update: Bolt's documentation covers signed secret setup in their tutorial)

So like the Socket Mode example above, the code may suffice before signing secrets get introduced, but it should be updated under current status. (Another example that possibly derived from the Socket Mode article, without mentioning need of signing secret.)