Authentication

Lark supports anonymous and token-based authentication. You choose how to authenticate when you connect, and you can change authentication state after connecting.

Anonymous authentication

The simplest option. Connect without any user identity:

import { LarkDatabase } from "@lark-sh/client";

const db = new LarkDatabase("my-project/my-database", { anonymous: true });

Anonymous connections are not assigned a UID and auth will be null for any security rules checks. You can still choose to let anonymous users read or modify data in your app by setting your security rules appropriately.

Token-based authentication

For identified users, pass a JWT when creating the instance:

const db = new LarkDatabase("my-project/my-database", {
  token: "eyJhbGciOiJIUzI1NiIs...",
});

The token contains the user’s identity (UID, provider, custom claims) and is validated by the Lark server. Your security rules can then reference auth.uid, auth.provider, and any custom claims.

See the platform authentication docs for details on how to generate JWTs for your users.

Changing auth state after connecting

You don’t have to authenticate at connect time. You can sign in or out at any point after connecting. Authenticate with a new token. If you were previously anonymous or signed in as a different user, the auth state updates:

// Start anonymous
const db = new LarkDatabase("my-project/my-database", { anonymous: true });
await db.connect();

// Later, sign in with a token
await db.signIn("eyJhbGciOiJIUzI1NiIs...");

`db.signOut()`

Reverts to anonymous authentication:

await db.signOut();

After calling signOut(), the connection stays open. You’re still connected, just without user identity. Any subscriptions that depend on authenticated access (via security rules) may stop receiving updates.

The `auth` property

Access the current authentication state at any time:

// When signed in
console.log(db.auth);
// { uid: "user-123", provider: "custom", token: "eyJ..." }

// When anonymous
console.log(db.auth);
// null

Property	Type	Description
`uid`	`string`	The user’s unique identifier.
`provider`	`string`	The authentication provider (e.g., `"custom"`, `"google"`).
`token`	`string`	The raw JWT.

Listening for auth changes

Use db.onAuthStateChanged(callback) to react to sign-in and sign-out events:

const unsubscribe = db.onAuthStateChanged((auth) => {
  if (auth) {
    console.log("Signed in as:", auth.uid);
  } else {
    console.log("Signed out (anonymous)");
  }
});

// Stop listening
unsubscribe();

The callback fires immediately with the current auth state, then again whenever it changes.

Full example

import { LarkDatabase } from "@lark-sh/client";

const db = new LarkDatabase("my-project/my-database", { anonymous: true });

// Listen for auth state changes
db.onAuthStateChanged((auth) => {
  if (auth) {
    console.log(`Welcome, ${auth.uid}`);
    loadUserData(auth.uid);
  } else {
    console.log("Not authenticated");
    showLoginScreen();
  }
});

// When the user logs in through your app's UI
async function handleLogin(token: string) {
  await db.signIn(token);
  // onAuthStateChanged fires with the new auth state
}

// When the user logs out
async function handleLogout() {
  await db.signOut();
  // onAuthStateChanged fires with null
}

Getting started

Guides

API reference

Authentication

Authentication

Anonymous authentication

Token-based authentication

Changing auth state after connecting

`db.signOut()`

The `auth` property

Listening for auth changes

Full example

​Authentication

​Anonymous authentication

​Token-based authentication

​Changing auth state after connecting

​db.signIn(token)

​db.signOut()

​The auth property

​Listening for auth changes

​Full example

Authentication

Anonymous authentication

Token-based authentication

Changing auth state after connecting

`db.signIn(token)`

`db.signOut()`

The `auth` property

Listening for auth changes

Full example