---
title: Authentication Configuration
tab: developer
---

This document describes the authentication methods available in the Business Platform and how to configure them.

## Overview

The Business Platform uses [Better Auth](https://better-auth.com/) as its authentication foundation. The server configuration is managed through `createBetterAuthSharedConfig`, which sets up authentication plugins, trusted origins, and user field mappings.

## Authentication Methods

### Email / Password (Credentials)

Standard email and password authentication is enabled by default. Users can register and log in using their email address and a password.

### Social Providers

Social login providers can be configured by passing provider identifiers to the login widget and account management component. Supported provider IDs include:

- `github`
- `google`
- `microsoft-entra-id`

When a user clicks a social login button, the client sends a request to `/api/auth/link-social` or initiates the OAuth flow directly, depending on the context (login vs. account linking).

### Magic Link (Passwordless Email)

Magic link authentication allows users to sign in without a password. The user enters their email address and receives a one-time link that signs them in when clicked.

#### How It Works

The platform integrates the `magicLink` plugin from Better Auth. When a user requests a magic link:

1. The user enters their email in the **Magic Link** section on the login page.
2. A sign-in link is sent to their email address.
3. The link expires after **5 minutes**.
4. Clicking the link authenticates the user and redirects to the application.

No additional configuration is required — magic link support is enabled by default as part of the shared server configuration.

#### API Endpoint

| Endpoint | Method | Description |
|---|---|---|
| `/api/auth/sign-in/magic-link` | POST | Sends a magic link email. Expects `{ email, callbackURL }`. |

### Passkeys (WebAuthn)

Passkey authentication is enabled by default as part of the base server configuration. No additional setup is required to activate it.

#### How It Works

Passkeys use the [WebAuthn API](https://webauthn.io/) to provide phishing-resistant, passwordless authentication. The platform integrates the `@better-auth/passkey` plugin on the server and `@simplewebauthn/browser` on the client.

The passkey plugin is included automatically in the shared BetterAuth configuration:

```typescript
// packages/server/src/auth/better-auth.server.ts
plugins: [passkey()]
```

This means any application instance built on top of the shared config inherits passkey support without additional configuration.

#### API Endpoints

The passkey plugin exposes the following endpoints under `/api/auth/passkey/`:

| Endpoint | Method | Description |
|---|---|---|
| `generate-register-options` | GET | Returns WebAuthn registration options. Accepts an optional `?name=` query parameter to label the passkey. |
| `verify-registration` | POST | Verifies the registration response from the authenticator and stores the credential. |
| `generate-authenticate-options` | GET | Returns WebAuthn authentication options for sign-in. |
| `verify-authentication` | POST | Verifies the authentication response and establishes a session. |
| `list-user-passkeys` | GET | Returns all passkeys registered to the authenticated user. |
| `delete-passkey` | POST | Removes a passkey by ID. Expects `{ id: string }` in the request body. |

#### Login with a Passkey

The login widget displays a **Login with Passkey** button automatically when the browser supports WebAuthn (`window.PublicKeyCredential` is defined). No configuration is needed to show this button.

```svelte
{#if supportsWebAuthn}
  <button onclick={loginWithPasskey}>
    Login with Passkey
  </button>
{/if}
```

After successful authentication, the page reloads to reflect the new session.

#### Managing Passkeys

Authenticated users can manage their passkeys from the **User Profile** panel via the `AuthMethodsManagementComponent`. This component allows users to:

- **Add a passkey** — Optionally provide a label/name, then complete the WebAuthn registration ceremony using their device authenticator.
- **Delete a passkey** — Remove a previously registered passkey by ID.

#### Browser Support

The passkey UI is conditionally rendered based on browser support:

```typescript
const supportsWebAuthn =
  typeof window !== "undefined" &&
  window.PublicKeyCredential !== undefined;
```

Browsers that do not support WebAuthn will not see passkey-related UI elements.

## Account Management

Users can manage all their linked authentication methods from the User Profile panel. The `AuthMethodsManagementComponent` surfaces:

- **Linked social accounts** — View and unlink connected OAuth providers.
- **Passkeys** — Add or remove passkeys (see [Passkeys](#passkeys-webauthn) above).

### Linking a Social Provider

To link an additional social provider to an existing account, the component calls `/api/auth/link-social` with the provider name and the current page as the callback URL. On success, the user is redirected through the OAuth flow and returned to the same page.

### Unlinking a Social Provider

Unlinking sends a POST request to `/api/auth/unlink-account` with `{ providerId }`. The account list is refreshed automatically after a successful unlink.

## Trusted Origins

Trusted origins can be configured via the `trustedOrigins` field of `BetterAuthSharedConfigInput`. This is used to restrict cross-origin requests to known domains.

```typescript
createBetterAuthSharedConfig({
  trustedOrigins: ["https://your-domain.example.com"],
  // ...
});
```

## User Field Mapping

The platform maps the Better Auth `name` field to `displayName` in the underlying user collection:

```typescript
user: {
  fields: {
    name: "displayName"
  }
}
```

This ensures compatibility with the internal `COLLECTION_USERS` schema.