Better Auth Steam Plugin

0.1.1 verified Sat Apr 25 auth: no javascript

Steam OpenID 2.0 plugin for Better Auth, providing Steam login via two endpoints: GET /api/auth/steam/login and GET /api/auth/steam/callback. It adds a nullable unique steamId field on the user model and requires better-auth >= 1.4.0 and zod >= 4 as peer dependencies. Version 0.1.1 ships TypeScript types. Key differentiators: full Steam OpenID assertion validation using check_authentication, synthetic email generation for users without email, and customizable profile mapping.

Common errors

error Cannot find module 'better-auth-steam' ↓

cause Package not installed via pnpm/npm/yarn.

fix

Run 'pnpm add better-auth-steam' (or npm install / yarn add).

error TypeError: Cannot destructure property 'apiKey' of 'undefined' or 'null' ↓

cause Missing or undefined STEAM_API_KEY environment variable.

fix

Set the STEAM_API_KEY environment variable in your .env file or shell.

error Error: better-auth requires zod >= 4. Found zod 3.x.x. ↓

cause Incompatible zod version installed.

fix

Install zod >= 4: 'pnpm add zod@^4'

Warnings

gotcha Missing or empty STEAM_API_KEY environment variable will cause runtime errors during Steam profile fetch. ↓

fix Ensure STEAM_API_KEY is set in production and development environments. Validate with zod or a runtime check.

deprecated Since version 0.1.0, the plugin does not support custom callback base URL configuration. Redirects are bound to the current origin. ↓

fix If you need a custom callback URL, consider forking the plugin or using a reverse proxy.

breaking The plugin requires Better Auth >= 1.4.0. Using an older version will cause import or runtime errors. ↓

fix Upgrade Better Auth to version 1.4.0 or later.

gotcha The synthetic email domain defaults to 'steam.local' which may conflict with local development email setups. ↓

fix Override the syntheticEmailDomain option to a domain you control, or handle synthetic emails in your email verification flow.

Install

npm install better-auth-steam

yarn add better-auth-steam

pnpm add better-auth-steam

Imports

steamOpenID

wrong

const steamOpenID = require('better-auth-steam')

correct

import { steamOpenID } from 'better-auth-steam'

ESM-only import. CommonJS require() will fail.

steamOpenIDClient

wrong

import { steamOpenIDClient } from 'better-auth-steam'

correct

import { steamOpenIDClient } from 'better-auth-steam/client'

Client plugin is exported from the /client subpath, not the main entry.

SteamPluginOptions

wrong

import { SteamPluginOptions } from 'better-auth-steam'

correct

import type { SteamPluginOptions } from 'better-auth-steam'

Type-only import. Options interface is not a runtime value.

Quickstart

Server-side setup: imports Better Auth minimal client and steamOpenID plugin, configures with a Steam API key from environment variable.

import { betterAuth } from 'better-auth/minimal';
import { steamOpenID } from 'better-auth-steam';

export const auth = betterAuth({
  plugins: [
    steamOpenID({
      apiKey: process.env.STEAM_API_KEY ?? ''
    })
  ]
});