Keep an eye on your workspace with audit logs

Image credit: Pete Ryan

Slack Enterprise Grid organizations are a fantastic way to organize large teams, but with that additional functionality comes more complexity. Often this means needing to have a better understanding of how people are using the workspaces in a Grid org, or keeping a more proactive watch over the access and security of workspaces.

Slack recently introduced a new API, the Audit Logs API, to monitor what’s happening across an Enterprise Grid org. This data can be fed into a security information tool to provide analysis of your Slack workspaces alongside other communication tools. Or, you can write custom scripts to monitor access.

A few things to note about the Audit Logs API: It’s only available for Enterprise Grid customers; the API methods are not accessible on Slack’s free, standard, or plus plans. As the Audit Logs are intended to be used as a monitoring tool, they are read-only. The events themselves will show actions that happen within a workspace but won’t reveal actual content (such as message content.)

If you’re interested in feeding data about your workspaces into a monitoring tool like a SIEM application, are looking for more insight into how your organization is using Slack, or want to proactively monitor for security issues, the audit logs APIs may be what you’re looking for.

The audit events

The API consists of three RESTful endpoints, all starting from https://api.slack.com/audit/v1

• schemas is a sort of meta API that returns information about the objects that the API itself returns. This is most useful if you’re building a comprehensive tool for integrating with all of Slack’s audit events and it doesn’t require authentication.
• actions is another meta-level API that returns information about the type of events the API returns and includes a list of all the actions, with a short description of each. It doesn’t require authentication either.
• logs is the primary endpoint for receiving actual events from an organization. It works by specifying a set of filters for the type of events to receive and then returns all of the events that match that query. The filter parameters are: oldest, latest, limit, action, actor, and entity. This method does require authentication via an OAuth token with the auditlogs:read scope. (Refer to our full documentation for more information on how to retrieve the token call the API).

The events returned by the API are comprised of an actor, an action, an entity, and a context, where the actor takes an action on an entity within a context. The actor will always be a Slack user identified by their ID, such as W123456. The action is the thing that happened, such as logging in or downloading a file. The entity is the object that the actor took the action on, such as the workspace that they logged in to or the file that was downloaded. And the context will be where the action was taken and will always be either a Workspace or Enterprise org ID.

The actual actions are the heart of an Audit Log event and we’ve got a full list of actions you may be interested in. We support actions across the following entities: workspace or org, channel, user, app, and file.

The Audit Logs API is a powerful way to get a comprehensive overview of your Enterprise Grid org. Get started today and get more insight into your workspaces.

We’re also constantly adding new events as we add features to the Slack product. Additionally, if there are additional events you’d be interested in receiving, let us know.