Authentication

The model: two keys, one session

Every backend exposes two kinds of credential, and keeping them straight is most of understanding auth here.

• The anon key is public. It identifies your backend and grants anonymous, RLS-public access — it's meant to ship in your browser bundle. It does not identify a person. Row-level security, not key secrecy, is what protects data, so an anon key on its own can only reach rows your policies expose to everyone.
• The user session token is what authenticates a person. After a successful sign-in, the SDK stores the session and automatically attaches its token to subsequent requests. From then on, your RLS policies can key off the signed-in user's id — auth.uid()-style rules start matching, and each user sees only their own rows.

Session shape

A successful sign-in resolves to a Session. The SDK persists it for you, so you rarely read the token by hand:

Session = {
  user: { id, email } | null,
  token: string            // a signed JWT representing the user
}

Every auth call returns a Result — { data, error } — except the few noted below. Check error before trusting data.

Sign-in methods at a glance

Email/password, magic link, and email OTP are always available on every backend. The three managed OAuth providers — Google, GitHub, Apple — are operator-configured and shared, or you can bring your own per-backend OAuth credentials. Enable and manage OAuth providers and the "require MFA" setting from the console.

Email & password

The simplest path. signUp registers the account and signIn (alias signInWithPassword) returns a session. Both take { email, password } and return Result<Session>.

// Register
const { data, error } = await lingcode.auth.signUp({
  email: '[email protected]',
  password: 'a-strong-passphrase'
});

// Sign in (signInWithPassword is an alias)
const { data: session, error: err } = await lingcode.auth.signIn({
  email: '[email protected]',
  password: 'a-strong-passphrase'
});

if (!err) {
  console.log('signed in as', session.user.email);
}

After a successful call the SDK has already stored the session — your next lingcode.from(...) call goes out authenticated. You don't pass the token anywhere yourself.

Magic links

A magic link trades the password for a one-time link emailed to the user. You send the link; when the user clicks it they land back on your app with the session in the URL, and the SDK auto-finalizes it — which is why you rarely call verifyMagicLink directly.

// 1. Send the link
const { data, error } = await lingcode.auth.sendMagicLink({
  email: '[email protected]',
  redirectTo: 'https://your-app.example.com/welcome' // optional
});
// data => { sent: true }

// 2. On the page the link returns to, just await ready —
//    the SDK consumes the token from the URL for you.
await lingcode.ready;
const user = lingcode.auth.getUser(); // now populated

// (rarely needed) finalize a token by hand:
// await lingcode.auth.verifyMagicLink(tokenFromUrl);

Email OTP

OTP is the same idea as a magic link but with a short code the user types instead of a link they click — handy on mobile or when deep links are awkward. Send a code, then verify the code the user enters.

// 1. Send a code
await lingcode.auth.sendOtp({ email: '[email protected]' });
// => { sent: true }

// 2. Verify what the user typed
const { data: session, error } = await lingcode.auth.verifyOtp({
  email: '[email protected]',
  code: '482913'
});
if (!error) {
  // session is stored; user is signed in
}

OAuth (Google, GitHub, Apple)

OAuth hands sign-in off to a provider the user already trusts. signInWithOAuth takes a provider — 'google', 'github', 'apple', or a custom string — and performs a top-level navigation to that provider's consent screen. It returns void, not a Result, because the page is leaving; on return, the SDK auto-stores the session.

// Kicks off a full-page redirect to Google.
lingcode.auth.signInWithOAuth('google', {
  redirectTo: 'https://your-app.example.com/dashboard' // optional
});

Because it's a top-level navigation, don't expect code after this line to run with a result — the browser is already on its way to the provider. Handle the signed-in state on the page the user comes back to (await ready, then read the user).

Which providers are enabled?

Not every backend turns on every provider. Ask before you render the buttons — getProviders() returns a map of provider → availability, so you can show only the ones that work:

const providers = await lingcode.auth.getProviders();
// {
//   google: { available: true,  source: 'managed' },
//   github: { available: true,  source: 'byo' },
//   apple:  { available: false, source: null }
// }

if (providers.google?.available) {
  renderGoogleButton();
}

Reading auth errors from a redirect

If the provider round-trip failed (user cancelled, mis-configured client, etc.), the error code rides back on the URL. lastError() surfaces it so you can show a message after a redirect:

await lingcode.ready;
const err = lingcode.auth.lastError(); // e.g. 'access_denied' or null
if (err) showBanner(`Sign-in failed: ${err}`);

Multi-factor authentication (MFA)

A password or OAuth login proves the user knows a secret or controls an account — assurance level AAL1. MFA adds a second proof: a time-based one-time code from an authenticator app (TOTP — RFC 6238, 6 digits, a fresh code every 30 seconds, with ±1 step of drift tolerance so a slightly-off clock still verifies). Completing MFA raises the session to AAL2, the higher assurance level your sensitive operations can require.

The flow has two parts. Enroll once: the backend returns a secret plus a QR code, the user scans it into their authenticator app, and you verify a code to confirm the pairing. Verify thereafter: when a session needs AAL2, the user enters a current code and the session is promoted. If the backend has "MFA required" turned on, users must complete MFA before they're considered fully signed in.

MFA is driven through the REST endpoints below — enroll to get the secret and QR, then verify a code to reach AAL2:

// Enroll: returns { secret, qr_code } — render the QR for the user to scan
POST /api/cloud/be/<backend-id>/auth/mfa/enroll

// Verify a code to confirm enrollment / raise the session to AAL2
POST /api/cloud/be/<backend-id>/auth/mfa/verify   { "code": "482913" }

Full walkthrough, including turning on the required-MFA switch: Require MFA on your backend.

The token model

The session token is a signed JWT that represents the user. The SDK carries it for you, but it helps to know what's moving:

• Access vs. refresh. The access token authenticates requests and is short-lived; a refresh token exchanges for a fresh access token at the refresh endpoint when the access token ages out. The SDK manages this — you don't usually touch /auth/token/refresh directly.
• Assurance levels. A token carries its assurance level: AAL1 after password or OAuth, AAL2 after an MFA verify. Policies can require AAL2 for sensitive operations.
• Two ways apps authenticate. Requests carry either the anon key (as a Bearer token or ?apikey=) for anonymous / RLS-public access, or the user token (attached automatically by the SDK) for signed-in access. Same endpoints, different credential.

Reading the current user or token by hand, when you need to:

const user  = lingcode.auth.getUser();  // { id, email } | null
const token = lingcode.auth.getToken(); // string | null (the JWT)

await lingcode.auth.signOut(); // clears the stored session; resolves { error: null }

Under the hood (REST)

The SDK is a thin wrapper over these endpoints — reach for them directly if you're working outside JavaScript or want to see exactly what's happening. The base for a backend is https://lingcode.dev/api/cloud/be/<backend-id>. The sign-in and provider endpoints authenticate with the anon key (Bearer or ?apikey=); the MFA, refresh, and sign-out endpoints require the user token.

Method	Path	Body / notes
POST	/auth/signup	{ email, password }
POST	/auth/signin	{ email, password }
POST	/auth/magiclink/request	{ email, redirect_url }
POST	/auth/magiclink/verify	{ token }
POST	/auth/otp/request	{ email }
POST	/auth/otp/verify	{ email, code }
POST	/auth/apple/native	{ identity_token } — native Apple Sign In
POST	/auth/token/refresh	{ refresh_token } — requires user token
POST	/auth/signout	{ refresh_token } or { all: true } — requires user token
POST	/auth/mfa/enroll	→ { secret, qr_code } — requires user token
POST	/auth/mfa/verify	{ code } → session at AAL2 — requires user token
POST	/auth/mfa/challenge	requires user token
GET	/auth/mfa/factors	requires user token
DELETE	/auth/mfa/factors/:factorId	requires user token
GET	/auth/providers	→ { google:{available,source}, github:{…}, apple:{…} }
GET	/auth/oauth/:provider/start?redirect_url=…	→ 302 to the provider's consent screen

The OAuth round-trip finishes at a callback the platform owns:

GET/POST /api/cloud/auth/oauth/:provider/callback

// On success, redirects back to your redirect_url with:
//   ?lc_session=<jwt>
// On failure:
//   ?lc_error=<code>