devnotes: Skill for Claude Code

Socialite Authentication

Documentation

Use search-docs for detailed Socialite patterns and documentation (installation, configuration, routing, callbacks, testing, scopes, stateless auth).

Available Providers

Built-in: facebook, twitter, twitter-oauth-2, linkedin, linkedin-openid, google, github, gitlab, bitbucket, slack, slack-openid, twitch

Community: 150+ additional providers at socialiteproviders.com. For provider-specific setup, use WebFetch on https://socialiteproviders.com/{provider-name}.

Configuration key in config/services.php must match the driver name exactly — note the hyphenated keys: twitter-oauth-2, linkedin-openid, slack-openid.

Twitter/X: Use twitter-oauth-2 (OAuth 2.0) for new projects. The legacy twitter driver is OAuth 1.0. Driver names remain unchanged despite the platform rebrand.

Community providers differ from built-in providers in the following ways:

• Installed via composer require socialiteproviders/{name}
• Must register via event listener — NOT auto-discovered like built-in providers
• Use search-docs for the registration pattern

Adding a Provider

1. Configure the provider

Add the provider's client_id, client_secret, and redirect to config/services.php. The config key must match the driver name exactly.

2. Create redirect and callback routes

Two routes are needed: one that calls Socialite::driver('provider')->redirect() to send the user to the OAuth provider, and one that calls Socialite::driver('provider')->user() to receive the callback and retrieve user details.

3. Authenticate and store the user

In the callback, use updateOrCreate to find or create a user record from the provider's response (id, name, email, token, refreshToken), then call Auth::login().

4. Customize the redirect (optional)

• scopes() — merge additional scopes with the provider's defaults
• setScopes() — replace all scopes entirely
• with() — pass optional parameters (e.g., ['hd' => 'example.com'] for Google)
• asBotUser() — Slack only; generates a bot token (xoxb-) instead of a user token (xoxp-). Must be called before both redirect() and user(). Only the token property will be hydrated on the user object.
• stateless() — for API/SPA contexts where session state is not maintained