Set up sign-in, step by step

BuildBase runs the sign-in for your app. Your users press Sign in in your app, land on a sign-in page that BuildBase hosts for you, sign in there with the methods you chose, and come back to your app signed in. This page explains the pieces you set up in the BuildBase console, the order to set them up in, and how to test it all with an account of your own. The guides after it take each way of signing in one at a time.

The examples use an organization called Acme with one app, Acme Analytics, that will live at https://app.acme.example.

The pieces

The order to do things in

1. Connect an email sender, under Messaging, Sender accounts. Most methods send an email at some point: a verification code, a reset code or a sign-in link. See the email sender.
2. Create your app (a client) on the Settings tab, copy its secret, and add its redirect URLs.
3. Add the sign-in methods you want on the Methods tab. The guides below say what each one needs first.
4. Tick the methods on your app, in its Edit sheet, and press Update. A method shows on the sign-in page only once it is ticked on the app.
5. Decide who can sign up on the Sign-up tab, and turn on bot protection on the Security tab before you go live.
6. Make the page yours on the Sign-in page tab: name, logo, colours and words.
7. Test it with Test beside your app, using an account of your own.
8. Connect your app's code with the SDK.

Find the Authentication area

In the console's left rail, choose Users. The User management menu opens. Choose Authentication under Access. Everything on this page happens in its tabs: Settings, Methods, Sign-up, Security, SMS, Sign-in page, Domains and Agent readiness.

Your app and its redirect URLs

The Settings tab lists your apps. The How to connect your app guide on it walks through the whole connection in five steps.

1. Press Create auth client. Type a Title your team will recognise, such as Acme Analytics, keep the type Your app's sign-in, and press Create.
2. The console shows the organization ID, the client ID and the client secret. Copy the secret now, with Copy client secret or Copy all three: it is shown only once. If it is lost, Regenerate in the Edit sheet makes a new one.
3. Press I've copied the secret, then press Edit on the new app.
4. Under Redirect URLs, press Add redirect URL and type each address your app uses for signing in, for example http://localhost:3000/callback while you test on your computer and https://app.acme.example/callback for the live app.
5. Press Update at the bottom of the sheet.

A redirect URL has to match letter for letter: http or https, the domain, the port and the path, even a slash at the end. On your own computer (localhost) the port may differ. For an app with a subdomain per customer, one entry with a * as the first part covers them all, such as https://*.app.acme.example/callback. An address missing from the list stops sign-in with "Invalid redirect URL". The going-live checklist covers adding the live address.

Add a sign-in method

Open the Methods tab. Login methods lists the methods your organization has. Each row says, in one line, what the person signing in does.

Press Add auth method. Each choice says what it is for and what else it needs. Pick one, fill in what it asks for, and press Create. The guide for each method, listed at the end of this page, covers its fields.

A method your plan does not include is greyed out, and pointing at it says "Your plan does not include" and the feature. Signing in on a TV or in a command line tool is not a method here: it is a switch on an OAuth 2.0 client. See Device code sign-in.

Attach a method to your app

A method shows on the sign-in page only once it is ticked on the app. Adding it on the Methods tab is not enough.

1. Open the Settings tab and press Edit beside Acme Analytics.
2. Under Methods, tick each method this app should offer.
3. Press Update.

Each app keeps its own list, so a staff app can offer only Google while the customer app offers email and password too.

Check the preview

Open the Sign-in page tab. The settings for the page are on the left, and the Preview is on the right. It follows your name, logo, colours and words as you type, before you save, and switches between Sign in, Sign up and Forgot password, Light and Dark, and Desktop and Phone.

What people see

This is the real sign-in page for Acme Analytics with Email and password and Magic link ticked. The title uses the Name from the Sign-in page tab.

On a phone the card fills the screen.

Test with a test account

Try every change yourself before your users meet it. A test account is an ordinary account in your app, made with an address you can read.

1. On the Settings tab, press Test beside Acme Analytics.
2. Under Choose a redirect URL to test, tick the address to come back to.
3. Press Test session login. Your sign-in page opens in a new tab, the same way your app's Sign in button opens it. If nothing opens, allow pop-ups for the console in your browser.

4. Press Create account and sign up with an address of yours, then sign in the way your users will.
5. After signing in, the page sends you to the redirect URL you ticked. If your app is not running at that address yet, the browser shows that it cannot reach the page. That is expected: the sign-in itself worked.
6. Open Users under User management. The test account is in the list. To remove it, open it and press Delete, then Delete user now.

Use a new private browser window for each test, so a device you trusted in an earlier test does not skip a step.

The SDK in your app

Your developers connect your app's code once. The console's How to connect your app guide names the three values it needs:

import { ApiVersion, SaaSOSProvider, useSaaSAuth } from '@buildbase/sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <SaaSOSProvider
      serverUrl="https://api.console.buildbase.app"
      version={ApiVersion.V1}
      orgId={process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!}
      auth={{
        clientId: process.env.NEXT_PUBLIC_BUILDBASE_CLIENT_ID!,
        redirectUrl: 'https://app.acme.example/callback',
        callbacks: {
          // Your server swaps the code for a session with the client secret.
          handleAuthentication: async (code) => {
            const res = await fetch('/api/auth/verify', {
              method: 'POST',
              body: JSON.stringify({ code }),
            });
            return { sessionId: (await res.json()).sessionId };
          },
        },
      }}
    >
      {children}
    </SaaSOSProvider>
  );
}

export function SignInButton() {
  const { signIn } = useSaaSAuth();
  return <button onClick={() => signIn()}>Sign in</button>;
}

The redirectUrl must be one of the app's Redirect URLs. The server route that swaps the code for a session is in Going to Production, and the full setup in the Quickstart.

Things to watch out for

• The client secret is shown once. Copy it when you create the app. If it is lost, Regenerate in the app's Edit sheet makes a new one, and your server needs the new one.
• A redirect URL is compared letter for letter. https://app.acme.example/callback and https://app.acme.example/callback/ are two different addresses. Only an address with no path and the same address ending in / count as one.
• A * stands for exactly one part of the address. https://*.app.acme.example/callback lets in https://eu.app.acme.example/callback, but not https://app.acme.example/callback or https://a.eu.app.acme.example/callback. The https://, the port and the path still have to match.
• A method you add does nothing until it is ticked on the app. Adding it on the Methods tab is not enough, and each app keeps its own list.
• The preview is a sample card. It always shows email and password, Email me a link, GitHub and Google. Check your real methods with Open the live page or Test.
• Most methods need an email sender. Without one, codes, links and password resets are refused with "Email sign-in is unavailable for this organization."
• A device you trusted skips steps. Test in a new private window each time, or a device you trusted earlier can hide a two-step code from you.

Every guide in this section

Next steps

• Email and password - the first method most apps add.
• Sign-in links and email codes - sign-in without a password.
• Authentication overview - the same features from the developer's side.