Auth Overview

To get the current user in your application, you can use the db.useUser hook.

import db from '../lib/db';

function Dashboard() {
  const user = db.useUser();

return <div>Signed in as: {user.email}</div>;
}

The useUser hook will throw an error if it is accessed while the user is not logged in, so it should be gated behind <db.SignedIn>.

import db from '../lib/db';

export default function App() {
  return (
    <div>
      <db.SignedIn>
        <Dashboard />
      </db.SignedIn>
      <db.SignedOut>
        <div>Log in to see the dashboard!</div>
      </db.SignedOut>
    </div>
  );
}

function Dashboard() {
  // This component will only render if the user is signed in
  // so it's safe to call useUser here!
  const user = db.useUser();

return <div>Signed in as: {user.email}</div>;
}

Use <db.SignedIn> and <db.SignedOut> to conditionally render components based on the user's authentication state.

You can then use db.auth.signOut() to sign a user out.

import db from '../lib/db';

// ... Same app component from above

function Dashboard() {
  const user = db.useUser();

return (
    <div>
      <div>Signed in as: {user.email}</div>
      <button onClick={() => db.auth.signOut()}>Sign out</button>
    </div>
  );
}

Putting it all together, you can conditionally render a login and dashboard component like so:

import db from '../lib/db';

export default function App() {
  return (
    <div>
      <db.SignedIn>
        <Dashboard />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </div>
  );
}

function Dashboard() {
  // This component will only render if the user is signed in
  // so it's safe to call useUser here!
  const user = db.useUser();

return <div>Signed in as: {user.email}</div>;
}

function Login() {
  // Implement a login flow here via magic codes, OAuth, Clerk, etc.
}

To implement a login flow use one of the authentication method guides below.

Authentication Methods

Magic Codes
Send login codes to your users via email. Removes the need for passwords.
Documentation
Guest Auth
Allow your users to try your app before they sign up.
Documentation
Google OAuth
We provide flows for Web and React Native to enable Google OAuth for your app.
Documentation
Sign In with Apple
Sign In to native apps with Apple ID.
Documentation
Github OAuth
Log in with Github on both Web and React Native.
Documentation
LinkedIn OAuth
Log in with LinkedIn on both Web and React Native.
Documentation
Clerk
Integrate Clerk's auth flow with Instant.
Documentation
Firebase Auth
Integrate Firebase's auth flow with Instant.
Documentation
Custom Auth
Integrate your own auth flow with the Admin SDK.
Documentation

Additional Auth APIs

Sometimes you need finer control over the state of auth in your application. In those cases, you can use some of the lower-level APIs.

useAuth

Use useAuth to fetch the current user. In this example we guard against loading our Main component until a user is logged in.

function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return null; // or a loading spinner
  }
  if (error) {
    return <div className="p-4 text-red-500">Uh oh! {error.message}</div>;
  }
  if (user) {
    return <Main />;
  }
  return <Login />;
}

Get auth

For scenarios where you want to know the current auth state without subscribing to changes, you can use getAuth.

const user = await db.getAuth();
console.log('logged in as', user.email);

Setting custom properties at signup

If you want to set custom properties on $users at signup time, see Setting properties at signup.

If you are an LLM trying to learn how to develop with Instant, here are all of the links to the docs: