# `PhoenixKit.Integrations.OAuth`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.102/lib/phoenix_kit/integrations/oauth.ex#L1)

Generic OAuth 2.0 flow for service integrations.

Handles authorization URL generation, code-to-token exchange,
token refresh, and userinfo fetching. Provider-specific details
(URLs, scopes, extra params) come from the provider definition
in `PhoenixKit.Integrations.Providers`.

# `authorization_url`

```elixir
@spec authorization_url(map(), map(), String.t(), String.t() | nil, String.t() | nil) ::
  {:ok, String.t()} | {:error, atom()}
```

Build the OAuth authorization URL for a provider.

Requires `client_id` to be present in the integration data and
the provider to have `oauth_config` with an `auth_url`.

# `exchange_code`

```elixir
@spec exchange_code(map(), map(), String.t(), String.t()) ::
  {:ok, map()} | {:error, term()}
```

Exchange an authorization code for access and refresh tokens.

# `fetch_userinfo`

```elixir
@spec fetch_userinfo(map(), String.t()) :: {:ok, map()} | {:error, term()}
```

Fetch user info from the provider's userinfo endpoint.

Returns a map with at least `"email"` if available.

# `generate_state`

```elixir
@spec generate_state() :: String.t()
```

Generate a random state token for CSRF protection in OAuth flows.

# `refresh_access_token`

```elixir
@spec refresh_access_token(map(), map()) ::
  {:ok, String.t(), map()} | {:error, term()}
```

Refresh an expired access token using the refresh token.

---

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