# `Slink.OAuth`
[🔗](https://github.com/wkirschbaum/slink/blob/v0.6.0/lib/slink/oauth.ex#L1)

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

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

1. Send the installer to Slack's consent screen — `authorize_url/1`.
2. Slack redirects back to your app with a short-lived `code`.
3. Exchange the code for that workspace's bot token — `exchange/2` (or let
   `Slink.OAuth.Plug` handle steps 2–3 as a mounted endpoint).
4. 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)

# `authorize_url`

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`

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).

---

*Consult [api-reference.md](api-reference.md) for complete listing*