Slink.OAuth (Slink v0.6.0)

The OAuth install flow for a multi-workspace ("Add to Slack") app.

Installing an app into a workspace is a standard OAuth v2 dance:

Send the installer to Slack's consent screen — authorize_url/1.
Slack redirects back to your app with a short-lived code.
Exchange the code for that workspace's bot token — exchange/2 (or let Slink.OAuth.Plug handle steps 2–3 as a mounted endpoint).
Persist {team_id, bot_token} in your own store, and hand it back per request via the transports' :bot_token resolver (see Multiple workspaces in Slink.EventsApi.Plug).

Slink does the Slack round-trips; the persistence is deliberately yours.

Example

# In a controller / LiveView: the "Add to Slack" link.
Slink.OAuth.authorize_url(
  client_id: client_id,
  scopes: ~w(app_mentions:read chat:write commands),
  redirect_uri: "https://example.com/slack/oauth/callback",
  state: my_csrf_token
)

# In the callback route (or mount Slink.OAuth.Plug instead):
{:ok, install} = Slink.OAuth.exchange(code,
  client_id: client_id,
  client_secret: client_secret,
  redirect_uri: "https://example.com/slack/oauth/callback"
)

MyApp.Installs.put(install.team_id, install.bot_token)

Summary

Functions

authorize_url(opts)

The Slack consent-screen URL an installer should be sent to.

exchange(code, opts)

Exchange the redirect's code for the workspace's tokens.

Functions

authorize_url(opts)

The Slack consent-screen URL an installer should be sent to.

Options:

:client_id (required) — the app's Client ID (Basic Information page).
:scopes (required) — bot scopes to request: a list or comma-string.
:redirect_uri — where Slack sends the installer back to (must be one of the app's configured Redirect URLs; optional when exactly one is configured there).
:state — an opaque value echoed back on the redirect. Use a value tied to the installer's session and check it in the callback (see Slink.OAuth.Plug's :verify_state) to prevent forged installs.
:user_scopes — user-token scopes, if the app requests any.
:team — a workspace id to pre-select on the consent screen.

exchange(code, opts)

Exchange the redirect's code for the workspace's tokens.

Calls oauth.v2.access with the app's client credentials and returns {:ok, %Slink.OAuth.Install{}}, or {:error, reason} — Slack's error string (e.g. "invalid_code" for an expired/reused code) or a transport error.

Options: :client_id and :client_secret (required; the secret may be a 0-arity function, resolved here), and :redirect_uri (required if the authorize URL carried one).