Overview

The SimpleAuth SDK (@simpleauthjs/core) is a lightweight JavaScript client for the SimpleAuth auth API. It works in browsers, Node.js, edge runtimes, and any environment with a fetch implementation.

Installation

npm install @simpleauthjs/core

Building a React app? See the React integration guide.

Two entry points

Import	Use case	API key
`@simpleauthjs/core`	Browser and client-side code	Public key (`sa_live_…`)
`@simpleauthjs/core/server`	Backend and server-side code	Secret key (`sa_secret_…`) or none for `currentUser`

// Client (browser)
import { createSimpleAuthClient } from "@simpleauthjs/core"

// Server (Node.js, Edge, etc.)
import { createServerSimpleAuthClient } from "@simpleauthjs/core/server"

Server-only import

@simpleauthjs/core/server throws an error if imported in a browser environment. This prevents accidentally shipping your secret key to clients.

Error handling

All SDK methods throw SimpleAuthError on failure. The error includes the HTTP status code, an error code, and a human-readable message.

import { SimpleAuthError } from "@simpleauthjs/core"

try {
  await auth.login({ email: "user@example.com", password: "wrong" })
} catch (error) {
  if (error instanceof SimpleAuthError) {
    console.error(error.status)  // 401
    console.error(error.code)    // "INVALID_CREDENTIALS"
    console.error(error.message) // "Invalid email or password"
  }
}

Error codes

Code	Meaning
`UNAUTHORIZED`	Missing or expired session.
`INVALID_API_KEY`	The API key is wrong or has been rotated.
`INVALID_CREDENTIALS`	Wrong email or password.
`VALIDATION_ERROR`	A required field is missing or malformed.
`USER_ALREADY_EXISTS`	A user with that email already exists.
`RATE_LIMITED`	Too many requests. Back off and retry.

Next steps

Client SDK — full reference for browser-side methods.
Server SDK — admin operations and session resolution on your backend.