46

I am looking for a call which could send a Slack team invitation email to a new user from my application. I searched it in the SlackAPI but I didn't find anything. Is it possible to create an application which would sent invitations on my behalf?
I'm currently using slacker as a Python wrapper, but if there is any better library which provides invitations I can start using it.

warownia1
  • 2,771
  • 1
  • 22
  • 30
  • No works in bash - i always got {"ok":false,"error":"invalid_email"} curl -X POST https://slack.com/api/users.admin.invite?token=$TOKEN&email=$EMAIL Also trying via: 1. 'Content-type: application/x-www-form-urlencoded' 2. --data-urlencode 3. --data – Olexandr Minzak Jul 25 '17 at 14:05
  • the error message means that is something wrong with the email address. however, some valid email addresses do not work. that is a known bug. – Erik Kalkoken Aug 29 '17 at 15:53

3 Answers3

106

Invite new users via API

There is an undocumented method in the Slack API that allows you to programmatically invite new users to your Slack workspace:

  • method name: users.admin.invite
  • arguments: token, email, channels
  • token: your slack API "test" token (required)
  • email: email address, e.g. email=test@email.com (required)
  • channels: comma separated list of channels the new user will auto-join. channels are specified by ID. e.g. channels=C000000001,C000000002(optional)

full example:

https://slack.com/api/users.admin.invite?token=XXX&email=test@email.com&channels=C000000001,C000000002

Note that this API method only works with legacy type tokens.

I started documenting the "undocumented" Slack API methods I know about including users.admin.invite. Check out the documentation on github.

Create new users via API

Alternatively there is an endpoint in the SCIM API to directly create new users:

POST /Users

However the SCIM API with all its endpoints is only available to Slack workspaces on the Plus plan or Enterprise Grid.

Important Update

Slack has decided to remove legacy tokens from their API. It will no longer be possible to create new legacy tokens as of May 5th, 2020 (Source). If you have a working legacy token you should be able to continue using the undocumented API methods, but new users will not. Please take this into consideration when deciding about using any of the methods from this repo in your apps.

Erik Kalkoken
  • 30,467
  • 8
  • 79
  • 114
  • I find this incredibly helpful. up up for this. – whalesingswee Mar 29 '16 at 10:19
  • Saved me from too much googling – Allen Linatoc Jun 29 '16 at 19:35
  • 4
    what's the specific required OAuth scope for this endpoint? the response said "client" was needed, but upon passing it it tells me it's deprecated – ratsimihah Feb 20 '17 at 16:24
  • hmm this looks like a conflicting scopes issue – ratsimihah Feb 20 '17 at 16:28
  • 1
    I am trying to invite user, But getting this error `{"ok":false,"error":"no_perms"}`, Any idea what permission do i need for just invite users? – Bipin Vayalu Apr 24 '17 at 13:14
  • Usually only admins can invite people, so the user aligned with the access token would need the admin role. – Erik Kalkoken Apr 24 '17 at 13:42
  • It looks like this undocumented endpoint no longer works. The response says `{"ok":false,"error":"missing_scope","needed":"client","provided":"..."}` and as far as I can tell the `client` scope does not exists – Kyle S. Jan 10 '18 at 18:51
  • No, it still works, but you need to use a legacy token for it, which also includes the client scope. – Erik Kalkoken Jan 10 '18 at 18:58
  • 7
    Found a way to create `legacy tokens` here: https://api.slack.com/custom-integrations/legacy-tokens. But I'm now getting a `"invalid_email"` error message... – Nico Prat Mar 12 '18 at 10:45
  • 1
    I created a legacy token and successfully triggered a Slack invite. Note that you'll get the `invalid_email` message if the email has a `+` character. – Loren Jun 28 '18 at 22:53
  • seems that this endpoint may be for paid teams only? The response I get in trying to use it is `'ok' => false, 'error' => 'paid_teams_only',` – Steven Grant Oct 13 '18 at 20:34
  • @StevenGrant No. The API endpoint is still working and does NOT require you to be on a paid tier. I just tested it again with a free tier Slack. – Erik Kalkoken Oct 13 '18 at 21:47
  • 1
    Thanks @ErikKalkoken - I was trying to make the user restricted and seems that feature is for paid accounts only. – Steven Grant Oct 13 '18 at 22:22
  • yes. there are some options that are indeed are for payed teams only. but the main function of the endpoint works for free teams too – Erik Kalkoken Oct 14 '18 at 01:46
  • Is it possible to send an invitation but not allow the person invited to invite others? (this guide is very helpful) – Hamish Anderson Aug 29 '19 at 04:59
  • 1
    You can control who can invite people in the workspace settings. It can be set by role, so you can e.g. restrict it to admins only. – Erik Kalkoken Aug 29 '19 at 09:05
  • They're deprecating the legacy tokens May 5th of this year, so it seems that this workaround won't work then forcing you to upgrade your slack tier. – hallmanitor Feb 24 '20 at 19:33
  • Indeed. Sad story, because it means that less open source communities will use Slack and rather move on to other products, e.g. Discord. For those interested: Here is the official communication: https://api.slack.com/changelog/2020-02-legacy-test-token-creation-to-retire – Erik Kalkoken Feb 24 '20 at 19:44
  • What is up with the 'admin.users.invite' endpoint being restricted to enterprise grid only? Don't normal workspaces (free/plus) want to invite new users? It seems absurd to restrict this functionality to enterprise users only. Like, hello, the team is inviting new members after all, they are going to upgrade soon enough so why does slack care about it, they're getting paid either way? – Aditya Anand Dec 07 '20 at 15:07
6

Sadly the undocumented endpoint for inviting new users (users.admin.invite) is no longer available for new workspaces, because it requires a legacy token.

But there is an alternative solution.

What the undocumented endpoint mostly does is sending an email to a specified email address containing an invitation link for your workspace. Here is how you can reproduce that functionality:

  • Manually create an invitation link for your workspace
  • Send an email containing the invitation link to new users

Note that invitation links expires after 2.000 invites, so you need a way to count usage and being notified when they need to be replaced.

Erik Kalkoken
  • 30,467
  • 8
  • 79
  • 114
0

As others have mentioned, there is no documented way of doing this for non-Enterprise plans.

If you want to automate invitations, you have two options:

  1. You may generate a non-expiring invitation URL and send it to users. This is no different from invitations that Slack sends.
  2. Use API token that identifies your authentication session.

The latter approach will work only if you are the admin of the workspace.

  1. Open Slack web app and intercept HTTP requests
  2. Send an invite using the Slack web app to a test user
  3. Find HTTP request that mentions slack.com/api/users.admin.inviteBulk
  4. Copy token parameter value from the HTTP request body.

Now you can use that token to construct users.admin.inviteBulk API request using your application.

The downside of this approach is that these tokens eventually expire.

Both methods require manual intervention:

  1. You need to refresh the URL every 2000 invitations
  2. You need to refresh the token every 30 days
Gajus
  • 69,002
  • 70
  • 275
  • 438