Monitoring workspace events with the Audit Logs API

Monitor what's happening in your Enterprise Grid organization using Slack's Audit Logs API. The Audit Logs API can be used by security information and event management (SIEM) tools to provide 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.

Please note the Audit Logs API is only available to Slack workspaces on Slack Enterprise Grid. These API methods will not work with Free, Standard, or Plus plans.

Overview
Who this is for
Installing
The audit event
Calling the API methods
- Endpoints
- Actions
Errors

What the Audit Logs API can do

The Audit Logs API is for monitoring the audit events happening in an Enterprise Grid organization to ensure continued compliance, to safeguard against any inappropriate system access, and to allow you to audit suspicious behavior within your enterprise.

The idea is to give Enterprise Grid organization owners the ability to query user actions in a workspace. With this API, you could:

Automatically feed Slack access data into an SIEM or other auditing tool
Proactively monitor for potential security issues or malicious access attempts
Write custom apps to gain insight into how your organization uses Slack

These API methods provide a view of the actions users perform in an organization. They do not enable monitoring of message content. If you need to proactively monitor the messages in a Slack organization or workspace for compliance reasons, you may consider an e-Discovery or Data Loss Prevention solution.

The Audit Logs API provides insight into audit events that are actually happening across a Slack organization and is therefore read only. There are no write methods for Audit Log events.

Slack also does not perform any kind of automated intrustion detection — the Audit Logs API will return the data but can not automatically determine whether an action was appropriate.

The Audit Logs API is launching with support for a subset of all possible Slack audit events. We will continue to add support for additional audit events.

Who this document is for

The Audit Logs API is meant for anyone interested in programatically monitoring audit events in a Slack Enterprise Grid organization. This may include:

Providers of SIEM solutions looking to integrate with Slack
Enterprise Grid administrators looking for insight into how their team is accessing Slack
Security professionals interested in actively monitoring their Slack organization for potential security issues

Installing an app on an Enterprise Grid org

Audit Logs events work across an entire Enterprise Grid organization, not individual workspaces. For this reason, the OAuth token used for calling Audit Logs API methods must be obtained from installing the app on the organization, not just a workspace within the organization.

To configure and install an app on your Enterprise Grid org:

The web service powering your app will need to be able to handle a standard OAuth 2 flow.
Create a new Slack app.
In the app's settings, select OAuth & Permissions from the left navigation. Scroll down to the section titled Scopes and add the auditlogs:read scope and click the green Save Changes button.
In the app's settings, select Manage Distribution from the left navigation. Under the section titled Share Your App with Other Workspaces, make sure all four sections have the green check. Then click the green Activate Public Distribution button.
Under the Share Your App with Your Workspace section, copy the Sharable URL and paste it into a browser to initiate the OAuth handshake that will install the app on your organization. You will need to be logged in as an administrator of your Enterprise Grid organization to install the app.
Check the dropdown in the upper right of the installation screen to make sure you are installing the app on the Enterprise Grid organization, not an individual workspace within the organization. (See image below.)
Once your app completes the OAuth flow, you will be granted an OAuth token that can be used for calling all of the Audit Logs API methods for your organization.

When installing an Audit Logs app, be sure to install it on your Grid organization, not a workspace within the organization. (See step 6 above.)

Installing the app on a workspace

The audit event

If the Slack workspace is a stage, all the members are merely actors. They have their exits and entrances and one user in time plays many parts.

Every audit event logged by the Audit Logs API is comprised of an actor, an action, an entity, and a context. They all work in harmony, such that the actor takes an action on an entity within a context.

The audit log events are returned to you as JSON, the exact format of which will vary slightly depending on the type of audit event. Each entry will describe the action, the actor that generated the event, the entity, and its context. Here's an audit event for a user logging in:

{
   "entries":[
      {
         "id":"0123a45b-6c7d-8900-e12f-3456789gh0i1",
         "date_create":1521214343,
         "action":"user_login",
         "actor":{
            "type":"user",
            "user":{
               "id":"W123AB456",
               "name":"Charlie Parker",
               "email":"bird@slack.com"
            }
         },
         "entity":{
            "type":"user",
            "user":{
               "id":"W123AB456",
               "name":"Charlie Parker",
               "email":"bird@slack.com"
            }
         },
         "context":{
            "location":{
               "type":"enterprise",
               "id":"E1701NCCA",
               "name":"Birdland",
               "domain":"birdland"
            },
            "ua":"Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/64.0.3282.186 Safari\/537.36",
            "ip_address":"1.23.45.678"
         }
      }
    ]
}

An actor will always be a user on a workspace and will be identified by their user ID, such as W123AB456. Occasionally, an event may fire without an actor, in which case Slack returns a placeholder actor object where the ID will always be USLACKUSER.

An action is the thing they did and it will be an easily identifiable string from the known list of actions. An example might be user_login, file_downloaded, or emoji_removed.

An entity is the thing that the actor has taken the action upon and it will be the Slack ID of the thing, such as a user (W123AB456), a channel (C987XYZ654), a file (F42424242), an app (A27182818), a workspace (T31415926), or an enterprise (E1701NCCA). For example, during a team member logging in audit event, the entity is that user. For a file that was downloaded, the entity is that file. For an emoji being removed, it is the workspace from which the emoji was removed. Like actions, the number of entities will continue to grow to include other Slack components.

Finally, the context is the location that the actor took the action on the entity. It will always be either a Workspace or an Enterprise, with the appropriate ID.

Some audit events may optionally include details where appropriate — for example, if it would be helpful to know the previous value of a setting that was changed.

How to call the Audit Logs API

The Audit Logs API is RESTful and, being read-only, uses a single HTTP verb — GET — to query and retrieve information. These methods will also return standard HTTP status codes to indicate success (or failure).

If you've used other Slack APIs before, such as the Web or Events APIs, the Audit Logs will be familiar but also a bit different. The Audit Logs are much more conceptually similar to Slack's SCIM API — for example, they are properly RESTful rather than REST-like.

The base URL for accessing the Audit Logs API methods is https://api.slack.com/audit/v1/. All of the endpoints detailed below branch from this base URL.

The Accept header of your HTTP request should be set to application/json.

Endpoints that require authentication must include an OAuth token as an Authorization header with a type of Bearer. The token must be a Slack user token (beginning with xoxp) associated with an Enterprise Grid organization owner (Grid organization administrator tokens are not currently supported) and the token must be granted the auditlogs:read OAuth scope. If you are having trouble generating this token, please contact our support team.

The Audit Logs API methods conform to Slack's rate limits and all methods are rated Tier 3. This allows for up to 50 calls per minute, with an allowance for sporadic bursts.

An example call to the Audit Logs API could look like the following:

    GET /audit/v1/logs HTTP/1.1
    Host: api.slack.com
    Accept: application/json
    Authorization: Bearer xoxp-1234567890-0987654321-1234567890-0987654321

Audit Logs endpoints

Use the following RESTful endpoints to access the methods of the Access Logs API.

GET /schemas Returns information about the kind of objects which the Audit Logs API returns as a list of all objects and a short description. Authentication not required.

GET /actions Returns information about the kind of actions that the Audit Logs API returns as a list of all actions and a short description of each. Authentication not required.

GET /logs This is the primary endpoint for retrieving actual audit events from your organization. It will return a list of actions that have occurred on the installed workspace or grid organization. Authentication required.

The following filters can be applied in order to narrow the range of actions returned. Filters are added as query string parameters and can be combined together. Multiple filter parameters are additive (a boolean AND) and are separated with an ampersand (&) in the query string. Filtering is entirely optional.

Filter key	Type	Description
`latest`	Integer	Unix timestamp of the most recent audit event to include (inclusive).
`oldest`	Integer	Unix timestamp of the least recent audit event to include (inclusive). The earliest possible timestamp is when the Audit Logs feature was enabled for your Grid organization, around mid-March 2018.
`limit`	Integer	Number of results to return, maximum `9999`.
`action`	String	Name of the action.
`actor`	String	User ID who initiated the action.
`entity`	String	ID of the target entity of the action (such as a channel, workspace, organization, file).

In the following example, you would receive all of the audit events for a specific user (W123AB456) who logged in (user_login) since March 16, 2018.

https://api.slack.com/audit/v1/logs?oldest=1521214343&action=user_login&actor=W123AB456

Slack will return a maximum of 9,999 audit events per API request, with the default ordering being descending (most to least recent). Use pagination to programmatically access more audit events, following the guidelines outlined in Slack's cursor-based pagination.

Audit Logs actions

The following tables outline the currently supported list of actions, organized by entity. This list will grow over time — if you don't see an action you are interested in keeping an eye on, please let us know.

Workspace or Org

Action	Description
`workspace_created`	A workspace in an organization was created.
`workspace_deleted`	A workspace in an organization was deleted.
`workspace_accepted_migration`	An administrator on a workspace has accepted an invitation to migrate to a Grid organization.
`workspace_declined_migration`	An administrator on a workspace has declined an invitation to migrate to a Grid organization.
`migration_scheduled`	A migration was scheduled.
`organization_created`	An Enterprise Grid organization was created.
`organization_deleted`	An Enterprise Grid organization was deleted.
`pref.sso_setting_changed`	The Single Sign On (SSO) restriction changed. Includes a `details` parameter noting the previous and new values.
`pref.two_factor_auth_changed`	The two-factor authentication requiremented changed. Includes a `details` parameter noting the previous and new values.
`pref.public_channel_retention_changed`	The channel retention setting type changed. Includes a `details` parameter noting the previous and new values.
`pref.private_channel_retention_changed`	The group (private channel) retention setting changed. Includes a `details` parameter noting the previous and new values.
`pref.dm_retention_changed`	The direct message (DM) retention setting changed. Includes a `details` parameter noting the previous and new values.
`pref.file_retention_changed`	The file retention setting changed. Includes a `details` parameter noting the previous and new values.
`pref.retention_override_changed`	The retention override setting, allowing workspace members to set their own retention period for private channels and DMs, changed. Includes a `details` parameter noting the previous and new values.
`billing_address_added`	A billing address was added. Includes a `details` parameter noting the timestamp the TOS was accepted.
`emoji_added`	An emoji was added. Includes a `details` parameter with the name of the emoji.
`emoji_removed`	An emoji was removed. Includes a `details` parameter with the name of the emoji.
`emoji_aliased`	An emoji was given an alias. Includes a `details` parameter with the name of the alias.
`emoji_renamed`	An emoji was renamed. Includes a `details` parameter with the previous and new names of the emoji.
`manual_export_started`	A workspace admin or owner has started a standard export on a workspace.
`manual_export_completed`	A standard export on a workspace has finished.
`corporate_exports_approved`	The corporate export feature has been approved for use on a workspace.
`corporate_exports_enabled`	The corporate export feature has been enabled for a workspace.
`scheduled_export_started`	A scheduled corporate export has started.
`scheduled_export_completed`	A scheduled corporate export has finished.

Channel

Action	Description
`user_channel_join`	A user has joined a channel.
`user_channel_leave`	A user has left a channel.
`guest_channel_join`	A guest user has joined a channel.
`guest_channel_leave`	A guest user has left a channel.
`public_channel_created`	A public channel was created.
`private_channel_created`	A private channel was created.
`public_channel_archive`	A public channel was archived.
`private_channel_archive`	A private channel was archived.
`public_channel_unarchive`	A public channel was unarchived.
`private_channel_unarchive`	A private channel was unarchived.
`public_channel_deleted`	A public channel was deleted.
`private_channel_deleted`	A private channel was deleted.

User

Action	Description
`role_change_to_owner`	A team member was made an owner.
`role_change_to_admin`	A team member was made an admin.
`role_change_to_user`	A team member was a user.
`role_change_to_guest`	A team member was made a guest.
`owner_transferred`	An owner was transferred.
`user_created`	A team member was created.
`user_deactivated`	A team member was deactivated.
`user_reactivated`	A team member was reactivated after having been deactivated.
`guest_created`	A guest was created.
`guest_deactivated`	A guest was deactivated.
`guest_reactivated`	A guest was reactivated after having been deactivated.
`guest_expiration_set`	A guest had an account expiration time set.
`guest_expired`	A guest was deactivated when the expiration time was reached.
`guest_expiration_cleared`	A guest had an expiration time cleared (before this time arrived).
`user_login`	A team member logged in.
`user_logout`	A team member logged out.
`custom_tos_accepted`	A team member accepted a custom terms of service agreement.

App

Action	Description
`app_approved`	On workspaces that have admin approved apps enabled, an app has been approved but not yet installed.
`app_installed`	An app has been installed. If a custom integration had been disabled, this event will also be triggered if it is re-enabled.
`app_scopes_expanded`	An app has been granted additional access to resources on a workspace, via OAuth scopes. For most apps, this requires a re-install. For workspace apps, this may also happen via the permissions API.
`app_resources_added`	Workspace apps have the ability to request access to a specific resource on a workspace, such as a channel or a DM, including wildcard resources (such as all public channels). This event is triggered when access has been granted.

File

Action	Description
`file_downloaded`	A file was downloaded.
`file_uploaded`	A file was uploaded.
`file_public_link_created`	A public link was created for a file.
`file_public_link_revoked`	A public link was revoked from a file.
`file_shared`	A file was shared in another channel.

Errors

Occasionally, interacting with our APIs will result in an error instead of, well, a result. Slack will make every attempt to respond with a descriptive error message that will help you figure out what went wrong and how to fix it.

Error	Description
`bad_endpoint`	The endpoint URL does not exist.
`feature_not_enabled`	Audit Logs are not available on your workspace, probably because it is not part of an Enterpise Grid organization.
`invalid_action`	The action is not supported.
`invalid_authentication`	The authentication token is not valid. Check that the token is associated with an Enterprise Grid owner and that it has the `auditlogs:read` scope.
`invalid_cursor`	The pagination cursor is invalid. Check that it matches the cursor that was returned by the previous request.
`invalid_workspace`	The Audit Logs API can not be used with this workspace, most likely because it not a part of an Enterprise Grid.
`invalid_range`	The range specified in the filter is not valid. This may indicate a date from before the feature was enabled or at some point in the future.
`method_not_allowed`	This method is not allowed on the workspace or with the token used.
`missing_authentication`	The OAuth token is either missing from the header of the request or malformed.
`rate_limited`	The app is calling the API too often. Please slow down.
`team_not_authorized`	The app is installed on a Slack workspace but needs to be installed on an Enterprise Grid organization.
`user_not_authorized`	The user who installed the app is not an Enterprise Grid owner — they must be an Enterprise Grid owner.

Going forward

The history of your workspace can be strange and eventful, and the Audit Logs API is here to help you keep a close watch on everything that happens, as you like it. We will continue to add audit events going forward, for both existing actions and to support new features.

Please don't hesitate to contact support if we can help with anything at all.