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

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.

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

Apps requesting the auditlogs:read scope must be installed by the Owner of an Enterprise Grid organization.

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 supporting Audit Logs on your Enterprise Grid organization:

  1. The web service powering your app will need to be able to handle a standard OAuth 2 flow.
  2. Create a new Slack app.
  3. 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.
  4. 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.
  5. 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 must be logged in as the Owner of your Enterprise Grid organization to install the app.
  6. 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.)
  7. 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 optimistically 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.

You may receive more than the passed limit results from a given request if there are multiple logs that were recorded at the exact same time.

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.
organization_accepted_migration The Org Owner accepted a workspace invitation to join their organization.
organization_declined_migration The Org Owner declined a workspace invitation to join their organization.
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.
message_tombstoned A message was tombstoned.
message_restored A message was restored.
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.
channels_export_started A channel export has begun.
channels_export_completed A channel export is complete.

Workspace or Org preferences

Action Description
pref.allow_calls A preference indicating whether Slack Calls can be used in this workspace has changed.
pref.allow_message_deletion Someone altered this workspace's settings around whether messages can be deleted or not.
pref.app_dir_only Whether only Slack App Directory apps can be installed or not in this workspace has changed.
pref.app_whitelist_enabled Someone's carefully carved or culled the list of apps this workspace has whitelisted.
pref.can_receive_shared_channels_invites Whether this workspace can receive invites to share channels with other workspaces has changed.
pref.commands_only_regular The setting determining whether restricted users are restricted from using slash commands was changed.
pref.custom_tos This workspace's settings on having a custom terms of service have changed.
pref.disallow_public_file_urls This workspace has modified their public file URL settings for files uploaded within it.
pref.dm_retention_changed The direct message (DM) retention setting changed. Includes a details parameter noting the previous and new values.
pref.dnd_enabled Do not disturb settings have been enabled for a workspace.
pref.dnd_end_hour The exact ending hour for workspace do not disturb settings has been set. Work hard and go home.
pref.dnd_start_hour The exact starting hour for workspace do not disturb settings has been set. Hopefully everyone is awake and ready to work by then.
pref.emoji_only_admins Someone modified the list of emoji-administrating admins, so you know who stole the cookies from the cookie jar.
pref.enterprise_default_channels Someone modified the list of default channels across the enterprise grid.
pref.enterprise_team_creation_request Someone has requested that your organization allow a new workspace to be created.
pref.file_retention_changed The file retention setting changed. Includes a details parameter noting the previous and new values.
pref.msg_edit_window_mins Someone edited the edit messaging window for a workspace!
pref.private_channel_retention_changed The group (private channel) retention setting 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.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.
pref.sign_in_with_slack_disabled This workspace changed their preference around allowing Sign in with Slack.
pref.slackbot_responses_disabled The settings around whether Slackbot's witty responses are enabled or disabled changed.
pref.slackbot_responses_only_admins There's a secret cabal of admins for those witty Slackbot responses and that list was changed.
pref.sso_setting_changed The Single Sign On (SSO) restriction changed. Includes a details parameter noting the previous and new values.
pref.stats_only_admins The list of admins that can work with workspace statistics only has changed.
pref.two_factor_auth_changed The two-factor authentication requiremented changed. Includes a details parameter noting the previous and new values.
pref.username_policy A workspace's username policy preference changed.
pref.who_can_archive_channels Who can archive channels indeed?
pref.who_can_create_delete_user_groups The list of who can create or delete user groups changed.
pref.who_can_create_private_channels It's like a who's who of who can create private channels, and it changed.
pref.who_can_create_public_channels The same as above, but for public channels.
pref.who_can_edit_user_groups The list of those who can edit user groups changed.
pref.who_can_manage_channel_posting_prefs Someone's been changing who can manage channel posting preferences
pref.who_can_manage_ext_shared_channels The list of who can manage externally shared channels has changed for this workspace.
pref.who_can_manage_guests The list of who can manage guests now has changed for this workspace.
pref.who_can_manage_shared_channels Settings around who can remove users from shared channels has changed for a workspace.
pref.who_can_remove_from_private_channels Settings around who can remove users from private channels has changed for a workspace.
pref.who_can_remove_from_public_channels Settings around who can remove users from public channels has changed for a workspace.

Enterprise Key Management (EKM)

Action Description
ekm_enrolled The workspace is now enrolled/managed by EKM.
ekm_unenrolled The workspace is no longer enrolled or managed by EKM.
ekm_key_added An EKM key was added for the workspace.
ekm_key_removed An EKM key was removed for the workspace.
ekm_clear_cache_set A revocation event has triggered a new TTL for cached date in this workspace.
ekm_logging_config_set Logging settings for this workspace's EKM configuration have changed.
ekm_slackbot_enroll_notification_sent Slack sent notifications about this workspace being enrolled in EKM.
ekm_slackbot_unenroll_notification_sent Slack sent notifications about this workspace no longer being enrolled in EKM.
ekm_slackbot_rekey_notification_sent Slack sent notifications about this workspace's EKM configuration being rekeyed.
ekm_slackbot_logging_notification_sent Slack sent notifications about logging changes to EKM in this workspace.

Channel

Action Description
user_channel_join A user has joined a channel. The user field in this action contains a team identifier so that you can see which team the joining user comes from (useful for externally shared channels).
user_channel_leave A user has left a channel. This action contains a team identifier so that you can see which team the departing user comes from (useful for externally shared channels).
guest_channel_join A guest user has joined a channel. This action contains a team identifier so that you can see which team the joining guest comes from (useful for externally shared channels).
guest_channel_leave A guest user has left a channel. This action contains a team identifier so that you can see which team the departing guest comes from (useful for externally shared channels).
guest_invite_sent A guest was invited to a channel. This action contains a team identifier so that you can see which team the inviting user comes from.
channel_moved A channel has been moved to a different workspace.
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.
mpim_converted_to_private A multi-party direct message was converted to a private channel.
public_channel_converted_to_private A channel which was once public is now private.

Shared channels

Action Description
external_shared_channel_connected A shared channel with another workspace has been connected with this one.
external_shared_channel_disconnected A shared channel with another workspace is no longer connected with this one.
external_shared_channel_reconnected A previously connected and then disconnected shared channel with another workspace is once again shared with this one.
external_shared_channel_invite_sent An invitation to join a shared channel was sent.
external_shared_channel_invite_accepted An invitation to join a shared channel was accepted! Nice.
external_shared_channel_invite_approved An invitation to join a shared channel was approved by an admin.
external_shared_channel_invite_created An invitation url to join a shared channel was created.
external_shared_channel_invite_declined An invitation to join a shared channel was declined.
external_shared_channel_invite_expired An invitation to join a shared channel expired.
external_shared_channel_invite_revoked An invitation to join a shared channel was revoked.

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.
app_uninstalled A Slack app was uninstalled.
app_token_preserved An app's token was preserved instead of revoked, usually due to an app owner or installer being removed from an organization.

File

Action Description
file_downloaded A file was downloaded.
file_downloaded_blocked A file was blocked from being downloaded.
file_uploaded A file was uploaded. This action contains a team identifier so that you can see which team the uploading user comes from (useful for externally shared channels).
file_public_link_created A public link was created for a file. This action contains a team identifier so that you can see which team the creating user comes from (useful for externally shared channels).
file_public_link_revoked A public link was revoked from a file. This action contains a team identifier so that you can see which team the revoking user comes from (useful for externally shared channels).
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.