Title: Social Providers

---

Overview

The Business Platform supports multiple authentication methods, including social (OAuth) providers, email/password credentials, and passkeys (WebAuthn). Users can link multiple authentication methods to a single account and manage them from their profile page.

Supported Providers

The following social providers are available for login and account linking:
GitHub — OAuth via GitHub accounts
Google — OAuth via Google accounts
Microsoft / Microsoft Entra ID — OAuth via Microsoft accounts
Additional providers may be configured by administrators

Linking and Unlinking Accounts

Auth Methods Management UI

Authenticated users can manage all their linked authentication methods directly from their profile page. The Auth Methods Management panel appears in the user profile and provides:
A list of currently linked social provider accounts
The ability to link additional social providers
The ability to unlink existing social provider accounts
Passkey (WebAuthn) management (see Passkeys)

Linking a Social Provider

To link a new social provider to your account:
Open your profile (click your avatar or user menu).
In the Auth Methods section, locate the list of available providers.
Click Link next to the provider you want to connect.
You will be redirected to the provider's authorization page.
After authorizing, you are returned to the platform with the provider linked to your account.

Internally, the platform posts to /api/auth/link-social with the chosen provider and your current page as the callbackURL. On success, the server returns a redirect URL and the browser navigates there automatically.

Unlinking a Social Provider

To unlink a social provider from your account:
Open your profile.
In the Auth Methods section, find the linked provider you want to remove.
Click Unlink next to that provider.

Note: Ensure you have at least one other authentication method (e.g., email/password or a passkey) before unlinking a provider, to avoid losing access to your account.

Unlinking calls /api/auth/unlink-account with the target providerId. If the request fails, an error message is displayed in the panel.

Passkeys

Passkeys use the WebAuthn standard to provide phishing-resistant, passwordless authentication. They are managed via the @better-auth/passkey plugin on the server and the @simplewebauthn/browser library on the client.

Browser Support

The passkey UI is only shown when the browser supports the WebAuthn API (window.PublicKeyCredential). Unsupported browsers will not display passkey options.

Signing In with a Passkey

On the login page, a Passkey button is shown alongside other login options when WebAuthn is supported. To sign in:
Click Login with Passkey.
Your browser or device will prompt you to authenticate (e.g., biometric, PIN, or security key).
On success, the page reloads and you are logged in.

Adding a Passkey

To register a new passkey from your profile:
Open your profile.
In the Auth Methods section, find the Passkeys area.
Optionally enter a name for the passkey (e.g., "MacBook Touch ID").
Click Add Passkey.
Follow your browser or device prompts to complete registration.

The platform calls /api/auth/passkey/generate-register-options to obtain registration options, then /api/auth/passkey/verify-registration to confirm the new credential.

Deleting a Passkey

To remove a registered passkey:
Open your profile.
In the Auth Methods section, find the passkey you want to remove.
Click Delete next to it.

Deletion calls /api/auth/passkey/delete-passkey with the passkey's id.

API Endpoints Reference

| Endpoint | Method | Description |
|---|---|---|
| /api/auth/list-accounts | GET | Returns all linked accounts for the current user |
| /api/auth/link-social | POST | Initiates linking a social provider |
| /api/auth/unlink-account | POST | Unlinks a social provider from the current user |
| /api/auth/passkey/generate-authenticate-options | GET | Returns WebAuthn authentication options |
| /api/auth/passkey/verify-authentication | POST | Verifies a passkey authentication response |
| /api/auth/passkey/generate-register-options | GET | Returns WebAuthn registration options |
| /api/auth/passkey/verify-registration | POST | Verifies a passkey registration response |
| /api/auth/passkey/list-user-passkeys | GET | Lists all passkeys registered to the current user |
| /api/auth/passkey/delete-passkey | POST | Deletes a passkey by ID |

Server Configuration

Passkey support is enabled automatically via the @better-auth/passkey plugin in better-auth.server.ts:

import { passkey } from "@better-auth/passkey";

// The plugin is included in the shared Better Auth configuration:
plugins: [passkey()]

No additional configuration is required for basic passkey support. Ensure your deployment is served over HTTPS, as WebAuthn requires a secure context.