Go to Slack

Working on behalf of users in workspace apps

Typically workspace apps help teams accomplish their workplace goals: analyzing data, posting notifications, handling collaborative interactions. Your workspace app has a lot to do in its own name.

After asking for permission, workspace apps can manage aspects of a user's Slack experience in more personal ways.

Imagine setting a custom status when users are out to lunch, continually adjusting do not disturb settings based on the latest work efficiency algorithms, or changing a user's display name as a special tribute to each day of the week. Your app can— with the right permission and agency.

Developer preview has ended

This feature was exclusive to our workspace apps developer preview. The preview has now ended, but fan-favorite features such as token rotation and the Conversations API will become available to classic Slack apps over the coming months.

Overview

Workspace apps may currently perform these operations on a user's behalf:

  • Reminders: investigate, list, create, remove, and mark them as complete.
  • User profile: read & write extended profile data about a user, including custom status.
  • Do not disturb: help users focus on work by automatically adjusting settings.
  • Sign in with Slack: look up user identity information for authorized users.

Before acting on a user's behalf, you must request their permission directly.

Asking users for permission

You can ask for a user's permission during the OAuth installation process or during the context of an conversational interaction using the Permissions API.

Asking during installation

To ask for user permissions during the OAuth installation sequence, ask for the user-related scopes you need in addition to any other scopes.

For example, if you want to read and edit reminders on behalf of the installing user, then ask for reminders:read:user and reminds:write:user.

If your app is already installed in a workspace, provide existing users a smoother experience by requesting their permission using the Permissions API.

During the final step of OAuth, oauth.access, Take note of the authorizing_user_id field. The response does not yet inform your app of any newly awarded user data scopes, so you'll have to become aware of them one of two ways:

  1. If you use the Events API, you can subscribe to user_resource_granted, user_resource_denied, and user_resource_removedto monitor user data permission grants.
  2. Use apps.permissions.users.list to find the awarded permissions at will.

Asking for permission in Slack with the Permissions API

Any user in a workspace can give your app permission to act on their behalf, but first you'll need to ask them with a special song and dance called a progressive permissions upgrade.

The typical dance steps are:

  1. Post an interactive message announcing your intentions and include a clearly labeled button.
  2. When a user clicks a button, your app's Action URL will receive a standard interactive message invocation, containing a trigger_id.
  3. You'll then use apps.permissions.users.request to formally request the specific scope.
  4. Use the workspace app token with the X-Slack-User HTTP header to act on behalf of the user.

Variations of this flow differ only in how you obtain the trigger_id. Instead of a message with a button, you could trigger the upgrade from an action, or a slash command invocation. Discover the wonderful things about triggers (and where to find them).

Learn more about using the Permissions API, asking for permissions progressively.

Tracking permissions over time

Subscribe to user_resource_granted, user_resource_removed, and/or user_resource_denied, to learn when user permissions are added, removed, or denied.

Use apps.permissions.users.list if you prefer retrieving at will.


Once your workspace token has the privilege, how do you actually work for users?

Using Web API methods as a user

When your app has permission to act on behalf of a user and is ready to do so, send the supported Web API method the same workspace token you typically use, but include an HTTP header called X-Slack-User. The value points to the user ID of the user you're performing an action for.

If you're familiar with traditional Slack apps and user tokens, you'll now find that, instead of having to store a separate token for each user that authorizes your app, you now need only store their user ID.

For example, if your user has a user ID like UA33221, your app sends X-Slack-User: UA33221. It's best to record these user IDs when permissions are granted to your app.

Here's an expanded example where our app sets a reminder for and as user WH1MPY. We're also presenting our token in the Authorization HTTP header and setting an explicit Content-type header.

POST /api/reminders.add
Authorization: Bearer xoxa-123456-abcdefghijklmop
X-Slack-User: WH1MPY
Content-type: application/json; charset=utf-8
{"text":"Pay Popeye back for that burger", "time": "every tuesday"}

Using Sign in with Slack

Sign in with Slack is a slight variation on the OAuth installation sequence focused on securely identifying a user. In addition to "signing users in," use Sign in with Slack to match a user to records you already have, or to provision a new account in your service.

Sign in with Slack is compatible with workspace apps, with minor differences in light of the single workspace token model.

Identity scopes

These identity scopes grant your app access to make requests to users.identity with your workspace token on behalf of the signed in user, using the X-Slack-User HTTP header.

To begin a Sign in with Slack sequence, ask for a combination of these scopes during OAuth exclusively— don't ask for any other scopes along with these.

  • identity:read:user - Access the user's identity and begin the Sign in with Slack sequence. You must ask for this scope in order to ask for any of the others below.
  • identity.email:read:user - In addition to the user's ID and name, gain access to their email address too.
  • identity.avatar:read:user - Also access their avatar, which is the image shown next to the messages they post.
  • identity.team:read:user - Learn about the workspace: its name and subdomain.

Please note: these scope names differ from the scopes used in traditional Slack apps.

Supported scopes, methods, & events

Here are the scopes and related methods currently supporting user agency:

Here's what dnd:write:user provides:

And here's what you can do with identity:read:user:

We needn't remind you what reminders:read:user is for:

And that's rounded out with reminders:write:user methods:

And don't forget, you can update a users custom status and other profile fields with users.profile:write:user:

Events

Track these Events API events to know whenever your app has received (or lost or didn't receive) new user permission resources.

Known issues

This is a new way to perform operations on behalf of users.

  • oauth.access doesn't report user-oriented scopes awards yet. You'll need to validate awarded scopes with the events above or use apps.permissions.users.list instead.
  • apps.permissions.users.request doesn't support application/json POST bodies yet. Please application/x-www-form-urlencoded for now.
  • You can still do "Sign in with Slack" the classic way, but we'll deprecate that soon. Use the new way.
  • We'd like to offer additional operations and user data perspectives. What do you want your app to do on behalf of users? Tell us!