Auth

Lux Auth adds app users, identities, sessions, OAuth providers, JWTs, and auth-owned system tables to a Lux project.

Mental model

Lux has two access layers. Direct RESP/Lux protocol access uses the database password and is meant for trusted infrastructure. App access goes through the project API with a project URL and key.

lux_pub_... keys are browser-safe and can call public auth endpoints.
lux_sec_... keys are server-only and can perform trusted project operations.
User sessions issue JWT access tokens and refresh tokens. Browser clients persist and refresh sessions by default.
Cloud manages project keys and routing. Lux core owns the auth tables and auth runtime behavior.

Browser app

Use createBrowserClient in browser apps. It stores the auth session in browser storage and sends the project key plus the user JWT on requests.

import { createBrowserClient } from "@luxdb/sdk";

const lux = createBrowserClient(
  "https://api.luxdb.dev/v1/my-project",
  "lux_pub_..."
);

const { data: signup, error: signupError } = await lux.auth.signUp({
  email: "user@example.com",
  password: "correct horse battery staple",
});

const { data: session, error: signInError } = await lux.auth.signInWithPassword({
  email: "user@example.com",
  password: "correct horse battery staple",
});

const { data: userResult } = await lux.auth.getUser();
console.log(userResult?.user);

OAuth

Lux currently supports Google and GitHub OAuth. In Lux Cloud, open the project Auth page, choose a provider, copy the callback URL into the provider console, then save the provider client ID and secret.

const { data, error } = await lux.auth.signInWithOAuth({
  provider: "google",
  redirectTo: "https://app.example.com/auth/callback",
});

Server app

Use createClient with a secret key only from trusted server code. Secret keys should never ship to browsers.

import { createClient } from "@luxdb/sdk";

const admin = createClient(
  "https://api.luxdb.dev/v1/my-project",
  process.env.LUX_SECRET_KEY!
);

const { data: users, error } = await admin.auth.listUsers();

Auth tables

When auth is enabled, Lux creates reserved auth.* tables. They are readable for inspection and foreign-key references, but mutation should go through the auth endpoints and SDK.

Table	Purpose
`auth.users`	Application users
`auth.identities`	Email and OAuth provider identities linked to users
`auth.sessions`	Refresh-token backed sessions
`auth.keys`	Auth API keys for self-hosted auth access
`auth.signing_keys`	JWT signing material
`auth.providers`	OAuth provider configuration

Self-hosting

On self-hosted Lux, auth is opt-in. Enable it with environment variables and expose the HTTP API so clients can reach /auth/v1.

LUX_AUTH_ENABLED=true \
LUX_AUTH_PUBLISHABLE_KEY=lux_pub_local \
LUX_AUTH_SECRET_KEY=lux_sec_local \
LUX_AUTH_ISSUER=http://localhost:8080/auth/v1 \
LUX_HTTP_PORT=8080 \
lux

Provider configuration is core-owned and uses the secret key.

curl -X PUT http://localhost:8080/auth/v1/admin/providers/google \
  -H "Authorization: Bearer lux_sec_local" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "GOOGLE_CLIENT_ID",
    "client_secret": "GOOGLE_CLIENT_SECRET",
    "redirect_uri": "http://localhost:8080/auth/v1/callback/google",
    "enabled": true
  }'

Build on Lux without guessing.