Client SDK
Complete reference for createSimpleAuthClient — every method, parameter, and return type.
Installation
npm install @simpleauthjs/corecreateSimpleAuthClient(options)
Creates a client instance for use in browsers and client-side code.
import { createSimpleAuthClient } from "@simpleauthjs/core"
const auth = createSimpleAuthClient({
apiKey: "sa_live_…",
})Options
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | — | Required. Your public API key (sa_live_…). |
baseUrl | string | "https://simpleauth.net" | API origin (no trailing slash). Falls back to process.env.SIMPLEAUTH_BASE_URL, then the default. Override when calling a local SimpleAuth server (for example http://localhost:3000). |
apiKeyTransport | "authorization" | "x-api-key" | "authorization" | How the API key is sent. "authorization" sends Authorization: Bearer <key>. "x-api-key" sends X-API-Key: <key>. |
credentials | RequestCredentials | "include" | Fetch credentials mode. Keep as "include" for cookie-based sessions. |
headers | Record<string, string> | {} | Extra headers merged into every request. |
timeoutMs | number | — | Request timeout in milliseconds. |
fetch | typeof fetch | globalThis.fetch | Custom fetch implementation. |
onError | (error: SimpleAuthError) => void | — | Called on every error before throwing. |
onRequest | (event) => void | — | Request tracing hook (secrets are redacted). |
onResponse | (event) => void | — | Response tracing hook. |
debug | boolean | false | Log requests and responses to the console. |
Methods
register(input, options?)
Create a new user account.
const { user } = await auth.register({
email: "user@example.com",
password: "s3cureP@ss",
name: "Jane Doe", // optional
})Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User's email address. |
password | string | Yes | Password for the account. |
name | string | No | Display name. |
Returns: { user: { id, email, name, emailVerified, createdAt } }
login(input, options?)
Sign in a user and start a session.
const { user } = await auth.login({
email: "user@example.com",
password: "s3cureP@ss",
})Parameters:
| Field | Type | Required |
|---|---|---|
email | string | Yes |
password | string | Yes |
Returns: { user } on success.
If the account is banned, the server responds with 403 and a SimpleAuthError. Handle this in your UI as a login failure.
getGoogleAuthUrl(input)
Returns the GET URL that starts the Google OAuth redirect (includes your public apiKey in the query string). Use this if you need to build a link yourself (for example in a server-rendered page).
const url = auth.getGoogleAuthUrl({
redirectUrl: "https://myapp.com/welcome",
})
// window.location.assign(url)Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
redirectUrl | string | Yes | Absolute URL on your app where users return after Google + SimpleAuth complete (origin must be allowlisted in the dashboard). |
Returns: string — URL under /api/external/auth/oauth/google/start?....
signInWithGoogle(input)
Browser only. Navigates the current tab to getGoogleAuthUrl so the user completes Google sign-in and lands back on your redirectUrl with a session cookie set on the SimpleAuth host.
auth.signInWithGoogle({
redirectUrl: "https://myapp.com/welcome",
})Throws: SimpleAuthError if called without window (SSR).
See also: Google sign-in guide.
getGithubAuthUrl(input)
Returns the GET URL that starts the GitHub OAuth redirect (includes your public apiKey in the query string).
const url = auth.getGithubAuthUrl({
redirectUrl: "https://myapp.com/welcome",
})
// window.location.assign(url)Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
redirectUrl | string | Yes | Absolute URL on your app where users return after GitHub + SimpleAuth complete (origin must be allowlisted in the dashboard). |
Returns: string — URL under /api/external/auth/oauth/github/start?....
signInWithGithub(input)
Browser only. Navigates the current tab to getGithubAuthUrl so the user completes GitHub sign-in and lands back on your redirectUrl with a session cookie set on the SimpleAuth host.
auth.signInWithGithub({
redirectUrl: "https://myapp.com/welcome",
})Throws: SimpleAuthError if called without window (SSR).
See also: GitHub sign-in guide.
me(options?)
Get the currently signed-in user from the session cookie.
const { user } = await auth.me()
console.log(user.email)Returns: { user: { id, email, name, emailVerified, createdAt } }
Throws: SimpleAuthError with status 401 if there is no active session.
logout(options?)
End the current session and clear auth cookies.
await auth.logout()Returns: { success: true }
isAuthenticated(options?)
Check whether the user has an active session. This calls me() internally and returns true or false without throwing.
if (await auth.isAuthenticated()) {
// user is logged in
}Returns: boolean
forgotPassword(input, options?)
Send a password reset email to the user.
await auth.forgotPassword({ email: "user@example.com" })Parameters: { email: string }
Returns: { success: true, message? }
resetPassword(input, options?)
Complete a password reset using the token from the email link.
await auth.resetPassword({
token: "reset-token-from-email",
password: "newP@ssword",
})Parameters:
| Field | Type | Required |
|---|---|---|
token | string | Yes |
password | string | Yes |
Returns: { success: true }
sendVerificationEmail(input, options?)
Send (or resend) the email verification link.
await auth.sendVerificationEmail({ email: "user@example.com" })Parameters: { email: string }
Returns: { success: true }
resendVerification is available as a deprecated alias. Use sendVerificationEmail instead.
verifyEmail(input, options?)
Confirm the user's email using the token from the verification link.
await auth.verifyEmail({ token: "verification-token" })Parameters: { token: string }
Returns: { success: true }
deleteAccount(input, options?)
Permanently delete the current user's account. Requires an active session and the user's password.
await auth.deleteAccount({ password: "currentP@ssword" })Parameters: { password: string }
Returns: { success: true }