Ulabase

Your users

Sign-up, login and invitations

The service handles registration, email verification, password reset, login with Google and team invitations for your app. You set the URLs and the emails.

The Sign-up and login feature gives your service registration, email verification, password reset, login with Google and team invitations. Your app shows the forms, and the service does the rest: it creates the account, sends the emails and checks the links in them.

Use it to let people create an account in your app and sign in. For example, a visitor registers with an email and a password, gets a verification email, clicks the link, and lands in your app signed in.

What you get:

  • No auth backend to write. The service stores the accounts, sends the emails and issues the tokens.

  • The client side done too. The Kit already wires your app’s forms to the service.

  • Your emails. You set the URLs the links point to, and the text of each email. The app’s name, color and logo come from Branding.

The Sign-up page: the feature enabled

Turn it on

Open Sign-up and login and click Enable. The page becomes the configuration form. Save applies every change at once; it takes up to a minute to reach every node of the service.

Tell it about your app

Field What it is for

Frontend URL

Where your app lives, such as https://app.example.com. Links in the emails are built from it.

Frontend app URL

Where a user lands after a link signs them in: after verifying their email, resetting a password, accepting an invitation or coming back from Google. Usually the app’s home for signed-in users, such as https://app.example.com/dashboard. Set it, or users land on the wrong page.

Choose the features

Each flow has a switch. Off, its endpoints answer 403.

Feature What the app calls

Registration and verification

POST /auth/register, then the link in the email hits GET /auth/verify and PATCH /auth/activate.

Password reset

POST /auth/forgot-password, then PATCH /auth/reset-password from the link in the email.

Team invitations

POST /auth/invite, GET /auth/teams, POST /auth/switch-team.

Social login (OAuth)

GET /auth/oauth/authorize/google, and the callback the service handles.

The Kit calls these for you: register(), login(), forgotPassword(), invite() and the rest.

Limits on sign-ups and invitations

Your plan limits how many sign-ups can wait for verification, how many teams a user can create, and how many invitations a team can have pending or send again. The numbers for each plan are on the Plans page. Enterprise has none of these limits.

  • Sign-ups not yet verified. The service counts the people who registered in the last 7 days and have not clicked their verification link yet. When the count reaches your plan’s number, new registrations get 429 until some of those people verify or their link expires after 7 days. An unverified account stays among your users, and stops counting when its link expires. The members of your team get an email the first time it happens in a day.

  • Teams per user. A user can create a limited number of teams, the one made at sign-up included. One more gets 403.

  • Pending invitations per team. A team can have a limited number of invitations waiting to be accepted. One more gets 403 until an invitation is accepted or expires.

  • Sending an invitation again. An invitation can be sent again 3 times, and not within 5 minutes of the last send. Too soon gets 429, a fourth time gets 403.

Each refusal has a code your app can act on, and a message written for the people who use your app:

Code Status When

unverified-cap

429

Too many sign-ups waiting for verification.

teams-cap

403

The user has created as many teams as allowed.

invitations-cap

403

The team has as many pending invitations as allowed.

resend-cooldown

429

The invitation was sent less than 5 minutes ago.

resend-cap

403

The invitation has been sent again 3 times.

The Kit puts the message in the error it throws, as message. The starters show it, and their resend button waits the 5 minutes by itself.

Login with Google

  1. In Google Cloud Console, open APIs & Services and configure the OAuth consent screen.

  2. Under Credentials, create an OAuth 2.0 Client ID of type Web application.

  3. In the OAuth section of the Sign-up page, switch Google on. The console shows the callback URL of your service, such as https://c0ffee.ulabase.app/auth/oauth/callback/google.

  4. Add that URL to the client’s Authorised redirect URIs.

  5. Paste the client ID and secret into the Sign-up page, and click Save.

Once saved, the secret is never shown again.

Google then also appears on the OAuth login page an AI agent opens when it connects to your service over MCP, with the same accounts. A user who signs in there for the first time gets an account, as they would from your app. See The OAuth login page.

The emails

The service sends three emails for you: verification after registration, password reset and invitation. They go out from noreply@ulabase.app with our templates and your Branding.

To write your own HTML, first set up your mail server on the Email page: your templates leave only from your own address. The editors on this page then open. Paste your HTML, click Fill default to start from ours, and Preview to see it rendered. The {{first-name}}, {{verification-url}}, {{reset-url}}, {{invite-url}}, {{inviter-name}}, {{team-name}} and {{year}} placeholders are filled when the mail is sent; {{app-name}}, {{app-color}}, {{app-color-fg}} and {{app-logo}} are your Branding.

The subject of the email is the <title> of the template. To write an email in more languages, wrap each version in <span lang="…">: a user gets the version of their locale field, or en when they have none. Our templates are in English and Italian.

Do it from the command line

You can keep everything on this page in git and apply it with ulabase setup: the app, the features, Google and the email templates. The templates are HTML files next to the setup file.

import { readFileSync } from 'node:fs';
import { defineSetup, step, fromEnv, isRedacted } from '@ulabase/cli';

// the three emails, as HTML files in the repository
const templates = {
  verification: readFileSync('emails/verification.html', 'utf8'),
  'password-reset': readFileSync('emails/password-reset.html', 'utf8'),
  invite: readFileSync('emails/invite.html', 'utf8'),
};

export default defineSetup('Sign-up', [
  // step 1: install the sign-up feature, if it is not installed yet
  step('accounts feature installed', {
    check: ({ admin, srvId }) => admin.isFeatureInstalled(srvId, 'accounts'),
    apply: ({ admin, srvId }) => admin.installFeature(srvId, 'accounts'),
  }),

  // step 2: save the app settings, the sign-up flows, Google login and the templates
  step('sign-up configured', {
    async check({ admin, srvId }) {
      const c = await admin.getFeatureConfig(srvId, 'accounts');
      const stored = (c.templates ?? {}) as Record<string, string>;
      return c['frontend-url'] === 'https://app.example.com'
          && Object.entries(templates).every(([k, v]) => stored[k] === v);
    },
    async apply({ admin, srvId }) {
      // read the configuration first, so the fields not written here stay as they are
      const current = await admin.getFeatureConfig(srvId, 'accounts');
      const google = (current.oauth as any)?.google ?? {};
      await admin.updateFeatureConfig(srvId, 'accounts', {
        ...current,
        'frontend-url': 'https://app.example.com',
        'frontend-app-url': 'https://app.example.com/dashboard',
        // the sign-up flows to turn on
        features: {
          registration: true,
          verification: true,
          'password-reset': true,
          invitations: true,
          oauth: true,
        },
        oauth: {
          google: {
            enabled: true,
            'client-id': fromEnv('GOOGLE_CLIENT_ID'),
            // the server never returns a saved secret: it sends '••••••••' in its place; send that back and the server keeps the saved secret
            'client-secret': isRedacted(google['client-secret'])
              ? google['client-secret']
              : fromEnv('GOOGLE_CLIENT_SECRET'),
          },
        },
        // leave an email out of templates and the service sends our template for it
        templates,
      });
    },
  }),
]);

The service stores the HTML of each template. To go back to our template for an email, leave its key out of templates. You cannot read our templates from the command line: copy them with Fill default in the console and save them in your repository.

The service never returns the saved Google secret: it sends •••••••• in its place. If you send •••••••• back, the service keeps the saved secret. Changes reach every node within a minute, as from the console.

What users cannot do to themselves

With the feature on, a user cannot change their own roles, active team or verification status through the /users API, whatever their permission says. Only registration, verification and invitations write those fields, through their own endpoints. So a user who may edit their profile cannot make themselves admin. Exemptions are described in accounts security.

  • The Ulabase Kit: the client side of every flow here.

  • Users: the accounts these flows create.

  • Guards: for instance, block a user who has not accepted the current terms.

  • Email: quotas and your own sender address.