You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/content/audit-logs.md
+15-41Lines changed: 15 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,20 @@
1
-
# Audit Logs API Client
1
+
# Audit Logs API client
2
2
3
-
[Audit Logs API](https://api.slack.com/admins/audit-logs) is a set of APIs for monitoring what's happening in your [Enterprise Grid](https://api.slack.com/enterprise/grid) organization.
3
+
The [Audit Logs API](https://docs.slack.dev/admins/audit-logs-api) is a set of APIs that you can use to monitor what's happening in your [Enterprise Grid](https://docs.slack.dev/enterprise-grid) organization.
4
4
5
-
The Audit Logs API can be used by security information and event management (SIEM) tools to provide an analysis of how your Slack organization is being accessed. You can also use this API to write your own applications to see how members of your organization are using Slack.
5
+
The Audit Logs API can be used by Security Information and Event Management (SIEM) tools to provide an analysis of how your Slack organization is being accessed. You can also use this API to write your own apps to see how members of your organization are using Slack.
6
6
7
-
Follow the instructions in [the API document](https://api.slack.com/admins/audit-logs) to get a valid token for using Audit Logs API. The Slack app using the Audit Logs API needs to be installed in the Enterprise Grid Organization, not an individual workspace within the organization.
7
+
You'll need a valid token in order to use the Audit Logs API. In addition, the Slack app using the Audit Logs API needs to be installed in the Enterprise Grid organization, not an individual workspace within the organization.
8
8
9
9
---
10
10
11
-
## AuditLogsClient
11
+
## AuditLogsClient {#auditlogsclient}
12
12
13
-
An OAuth token with [the admin
14
-
scope](https://api.slack.com/scopes/admin) is required to access this
15
-
API.
13
+
An OAuth token with [the admin scope](https://docs.slack.dev/reference/scopes/admin) is required to access this API.
16
14
17
-
You will likely use the `/logs` endpoint as it's the essential part of
18
-
this API.
15
+
You'll likely use the `/logs` endpoint as it's the essential part of this API.
19
16
20
-
To learn about the available parameters for this endpoint, check out
To learn about the available parameters for this endpoint, check out [using the Audit Logs API](https://docs.slack.dev/admins/audit-logs-api). You can also learn more about the data structure of `api_response.typed_body` from [the class source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py).
is enabled. The retry handler retries if an API client encounters a
67
-
connectivity-related failure (e.g., Connection reset by peer).
53
+
With the default settings, only `ConnectionErrorRetryHandler` with its default configuration (=only one retry in the manner of [exponential backoff and jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)) is enabled. The retry handler retries if an API client encounters a connectivity-related failure (e.g., connection reset by peer).
68
54
69
-
To use other retry handlers, you can pass a list of `RetryHandler` to
70
-
the client constructor. For instance, you can add the built-in
71
-
`RateLimitErrorRetryHandler` this way:
55
+
To use other retry handlers, you can pass a list of `RetryHandler` to the client constructor. For instance, you can add the built-in `RateLimitErrorRetryHandler` this way:
Creating your own ones is also quite simple. Defining a new class that
87
-
inherits `slack_sdk.http_retry.RetryHandler` (`AsyncRetryHandler` for
88
-
asyncio apps) and implements required methods (internals of `can_retry`
89
-
/ `prepare_for_next_retry`). Check the built-in ones' source code for
90
-
learning how to properly implement.
70
+
You can also create one on your own by defining a new class that inherits `slack_sdk.http_retry RetryHandler` (`AsyncRetryHandler` for asyncio apps) and implements required methods (internals of `can_retry` / `prepare_for_next_retry`). Check out the source code for the ones that are built in to learn how to properly implement them.
91
71
92
72
```python
93
73
import socket
@@ -120,10 +100,4 @@ client = AuditLogsClient(
120
100
)
121
101
```
122
102
123
-
For asyncio apps, `Async` prefixed corresponding modules are available.
124
-
All the methods in those methods are async/await compatible. Check [the
For asyncio apps, `Async` prefixed corresponding modules are available. All the methods in those methods are async/await compatible. Check [the source code](https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/http_retry/async_handler.py) for more details.
Copy file name to clipboardExpand all lines: docs/content/index.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
# Python Slack SDK
2
2
3
-
The Slack Python SDK has corresponding package for Slack APIs. They are small and powerful when used independently, and work seamlessly when used together, too.
3
+
The Slack Python SDK has corresponding packages for Slack APIs. They are small and powerful when used independently, and work seamlessly when used together, too.
4
4
5
-
The Slack platform offers several APIs to build apps. Each Slack API delivers part of the capabilities from the platform, so that you can pick just those that fit for your needs.
5
+
The Slack platform offers several APIs to build apps. Each Slack API delivers part of the capabilities from the platform, so that you can pick just those that fit your needs.
@@ -20,17 +20,17 @@ The Slack platform offers several APIs to build apps. Each Slack API delivers pa
20
20
21
21
You can also view the [Python module documents](https://tools.slack.dev/python-slack-sdk/api-docs/slack_sdk/)!
22
22
23
-
## Getting help
23
+
## Getting help {#getting-help}
24
24
25
25
These docs have lots of information on the Python Slack SDK. There's also an in-depth Reference section. Please explore!
26
26
27
-
If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
27
+
If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
28
28
29
29
*[Issue Tracker](http://github.com/slackapi/python-slack-sdk/issues) for questions, bug reports, feature requests, and general discussion related to the Python Slack SDK. Try searching for an existing issue before creating a new one.
These docs live within the [Python Slack SDK](https://github.com/slackapi/python-slack-sdk) repository and are open source.
35
35
36
-
We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/python-slack-sdk/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way.
36
+
We welcome contributions from everyone! Please check out our [Contributor's Guide](https://github.com/slackapi/python-slack-sdk/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way.
Making calls to the Slack API often requires a [token](https://docs.slack.dev/authentication/tokens) with associated scopes that grant access to resources.
46
-
47
-
Collecting a token can be done from app settings or with an OAuth installation depending on your app's requirements:
Making calls to the Slack API often requires a [token](https://docs.slack.dev/authentication/tokens) with associated scopes that grant access to resources. Collecting a token can be done from app settings or with an OAuth installation depending on your app's requirements.
51
45
52
46
**Always keep your access tokens safe.**
53
47
54
-
The OAuth token you use to call the Slack API has access to the data on
55
-
the workspace where it is installed.
56
-
57
-
Depending on the scopes granted to the token, it potentially has the
58
-
ability to read and write data. Treat these tokens just as you would a
59
-
password — don't publish them, don't check them into source code, and
60
-
don't share them with others.
48
+
The OAuth token you use to call the Slack Web API has access to the data on the workspace where it is installed. Depending on the scopes granted to the token, it potentially has the ability to read and write data. Treat these tokens just as you would a password — don't publish them, don't check them into source code, and don't share them with others.
61
49
62
50
:::danger
63
51
@@ -69,51 +57,34 @@ token = 'xoxb-111-222-xxxxx'
69
57
70
58
:::
71
59
72
-
We recommend you pass tokens in as environment variables, or persist
73
-
them in a database that is accessed at runtime. You can add a token to
74
-
the environment by starting your app as:
60
+
We recommend you pass tokens in as environment variables, or store them in a database that is accessed at runtime. You can add a token to the environment by starting your app as follows:
For additional information, please see the [Safely Storing
88
-
Credentials](https://api.slack.com/authentication/best-practices) page within the Slack API docs.
73
+
Refer to our [best practices for security](https://docs.slack.dev/authentication/best-practices-for-security) page for more information.
89
74
90
-
## Workspace Installations
75
+
## Installing on a single workspace {#single-workspace}
91
76
92
-
### Single Workspace Install
77
+
If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow. Once you've set up your features, click the **Install App to Team** button on the **Install App** page. If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for the changes to take effect.
93
78
94
-
If you're building an application for a single Slack workspace, there's no need to build out the entire OAuth flow.
79
+
Refer to the [quickstart](https://docs.slack.dev/quickstart) guide for more details.
95
80
96
-
After [creating an app](https://api.slack.com/apps?new_app=1) and adding [scopes](http://docs.slack.dev/reference/scopes)on the **OAuth & Permissions** page, go to the **Install App** page and click the **Install to Team** button to authorize the app and generate a token.
81
+
## Installing on multiple workspaces {#multi-workspace}
97
82
98
-
If you add new permission scopes or Slack app features after an app has been installed, you must reinstall the app to your workspace for changes to take effect.
83
+
If you intend for an app to be installed on multiple Slack workspaces, you will need to handle this installation via the industry-standard OAuth protocol. Read more about [installing with OAuth](https://docs.slack.dev/authentication/installing-with-oauth).
99
84
100
-
## Multiple Workspace Install
85
+
The OAuth exchange is facilitated via HTTP and requires a webserver; in this example, we'll use [Flask](https://flask.palletsprojects.com/).
101
86
102
-
If you intend for an app to be installed on multiple Slack workspaces,
103
-
you will need to handle this installation via the industry-standard
104
-
OAuth protocol. You can read more about [how Slack handles
(The OAuth exchange is facilitated via HTTP and requires a webserver; in
108
-
this example, we'll use [Flask](https://flask.palletsprojects.com/).)
109
-
110
-
To configure your app for OAuth, you'll need a client ID, a client
111
-
secret, and a set of one or more scopes that will be applied to the
112
-
token once it is granted. The client ID and client secret are available
113
-
from your [app's configuration page](https://api.slack.com/apps). The
114
-
scopes are determined by the functionality of the app — every method
115
-
you wish to access has a corresponding scope and your app will need to
116
-
request that scope in order to be able to access the method. Review the [full list of Slack OAuth scopes](http://docs.slack.dev/reference/scopes).
87
+
To configure your app for OAuth, you'll need a client ID, a client secret, and a set of one or more scopes that will be applied to the token once it is granted. The client ID and client secret are available from the [app page](https://api.slack.com/apps). The scopes are determined by the functionality of the app — every method you wish to access has a corresponding scope, and your app will need to request that scope in order to be able to access the method. Review the full list of [OAuth scopes](https://docs.slack.dev/reference/scopes).
To begin the OAuth flow that will install your app on a workspace,
133
-
you'll need to provide the user with a link to the Slack OAuth page.
134
-
This can be a simple link to `https://slack.com/oauth/v2/authorize` with
135
-
`scope` and `client_id` query parameters, or you can use our pre-built
136
-
[Add to Slack button](https://api.slack.com/docs/slack-button) to do all
137
-
the work for you.
103
+
To begin the OAuth flow that will install your app on a workspace, you'll need to provide the user with a link to the Slack OAuth page. This can be a simple link to `https://slack.com/oauth/v2/authorize` with the
104
+
`scope` and `client_id` query parameters.
138
105
139
-
This link directs the user to the Slack OAuth acceptance page, where the
140
-
user will review and accept or refuse the permissions your app is
141
-
requesting as defined by the scope(s).
106
+
This link directs the user to the OAuth acceptance page, where the user will review and accept or decline the permissions your app is requesting as defined by the scope(s).
142
107
143
108
```python
144
109
@app.route("/slack/install", methods=["GET"])
@@ -149,14 +114,9 @@ def pre_install():
149
114
'Add to Slack</a>'
150
115
```
151
116
152
-
### The OAuth completion page
117
+
### The OAuth completion page {#oauth-completion}
153
118
154
-
Once the user has agreed to the permissions you've requested, Slack
155
-
will redirect the user to your auth completion page, which includes a
156
-
`code` query string param. You'll use the `code` param to call the
157
-
`oauth.v2.access`
158
-
[endpoint](https://api.slack.com/methods/oauth.v2.access) that will
159
-
finally grant you the token.
119
+
Once the user has agreed to the permissions you've requested, Slack will redirect the user to your auth completion page, which includes a `code` query string parameter. You'll use the `code` parameter to call the [`oauth.v2.access`](https://docs.slack.dev/reference/methods/oauth.v2.access) API method that will grant you the token.
Once your user has completed the OAuth flow, you'll be able to use the
214
-
provided tokens to call any of the Slack API methods that require an
215
-
access token.
172
+
Once your user has completed the OAuth flow, you'll be able to use the provided tokens to call any of the Slack Web API methods that require an access token.
173
+
174
+
Refer to the [basic usage](https://tools.slack.dev/python-slack-sdk/legacy/basic_usage) page for more examples.
As the `slack` package is deprecated, we recommend switching to `slack_sdk`
250
-
package. That being said, the code you're working on may be still using
251
-
the old package. If you encounter an error saying
252
-
`AttributeError: module 'slack' has no attribute 'WebClient'`, run
253
-
`pip list`. If you find both `slack_sdk` and `slack` in the output, try
254
-
removing `slack` by `pip uninstall slack` and reinstalling `slack_sdk`.
206
+
As the `slack` package is deprecated, we recommend switching to `slack_sdk` package. That being said, the code you're working on may be still using the old package. If you encounter an error saying `AttributeError: module 'slack' has no attribute 'WebClient'`, run `pip list`. If you find both `slack_sdk` and `slack` in the output, try removing `slack` by `pip uninstall slack` and reinstalling `slack_sdk`.
0 commit comments