Skip to content
Zeitlos
Dashboard

Authentication

.md

Quickstart

Enable authentication and add sign-up, sign-in and the current user to your app.

Zeitlos authentication gives your app email and password accounts, email verification, password reset and custom profile fields. Sessions are httpOnly cookies, so there is no token to store.

Note

Authentication is reached through the SDK, and the SDK is TypeScript and JavaScript only for now. There is no official client for other languages yet.

Enable authentication

  1. Open your project in the dashboard and go to Authentication → Users.

  2. Choose "Enable authentication"

    A new project has no auth until you add it. Once enabled, the Users, Profile fields and Settings pages become usable.

  3. Review the settings

    Under Authentication → Settings you can turn sign-up on or off, require email verification, and set the name your emails come from.

Install the SDK

Terminal
npm install @zeitlosapp/sdk

Authentication lives on the same client as the database:

TypeScript
import { createClient } from '@zeitlosapp/sdk';

const client = createClient();

Unlike the database surface, the methods shown on this page are browser-safe , so you can call it from client components.

Sign up, in and out

app/sign-in.tsx
'use client';

import { createClient, ZeitlosError } from '@zeitlosapp/sdk';

const client = createClient();

async function signIn(email: string, password: string) {
  try {
    await client.auth.signIn({ email, password });
    // signed in — the session cookie is set
  } catch (err) {
    if (err instanceof ZeitlosError && err.code === 'INVALID_EMAIL_OR_PASSWORD') {
      // show "wrong email or password"
    }
  }
}
TypeScript
await client.auth.signUp({ email, password, name });
await client.auth.signOut();

The current user

TypeScript
const user = await client.auth.getUser(); // AuthUser | null

If the user isn't logged in, null will be returned.

In you want to call auth methods from a server-side function, you'll need to use the createClientForUser method instead of the createClient method. This will create a client who can call auth methods for the user calling this endpoint.

app/page.tsx
import { cookies } from 'next/headers';
import { createClientForUser } from '@zeitlosapp/sdk';

export default async function Page() {
  const client = createClientForUser({ cookies: await cookies() });
  const user = await client.auth.getUser();

  return <p>{user ? `Hello ${user.name}` : 'Not signed in'}</p>;
}

createClientForUser also accepts { request } or { headers }. Any of those allow the request, headers, or cookies to be passed into a range of formats, to be compatible with as many frameworks as possible.

Note

Use createClientForUser for server-side reads of the user and profile. Sign-in and sign-up should be done from the browser: those calls rely on the browser's Origin header for CSRF protection, and a plain server-to-server call without one is rejected.

Require email verification

Off by default. Turn on Require email verification under Authentication → Settings. With it on:

  • signUp creates the user but does not sign them in. Show a "check your email" screen.

  • signIn before verifying throws EMAIL_NOT_VERIFIED — catch it and offer a resend:

    TypeScript
    await client.auth.sendVerificationEmail({ email });

  • Clicking the link in the email is handled by Zeitlos. You need no specific implementation. The user is redirected back to your app — to the Post email verification URL configured in your project. If none is configured they are navigated to your apps domain with ?email_verified=true appended.

Password reset is different: it requires you to build a page in your app. See Password reset.

Next steps