SynqDocs
Guides

Build your own sign-in panel

List your brand's ways to sign in in your app's own UI, mark the one this browser last used, and know when a sign-in made a new account.

The hosted page lists your brand's ways to sign in, in the order its sign-in page places them, with the one this browser last used first and marked Last used. An app that draws its own sign-in panel (a sheet on a phone, a popover from a header button) gets the same from Synq, so a way you turn on or off in the dashboard shows up or goes away in the app with no deploy.

The example below is Acme Guild, a community app on its own brand with Google, X, a Solana wallet and emailed codes turned on.

The ways your app offers

GET /sign-in/methods?client_id= on your brand's issuer lists the ways your app's sign-in offers: those the brand has on and the app takes (Choose the ways to sign in), in the order the brand's sign-in page places them. It needs no credential, so it works for someone signed out, from your server or from your app's own pages: the issuer lets the origins of your app's redirect URIs read it.

curl "$ISSUER/sign-in/methods?client_id=$CLIENT_ID"
{
  "methods": [
    {
      "id": "google",
      "kind": "provider",
      "name": "Google",
      "icon": "$ISSUER/assets/signin-google-3f1c2a9b8d7e6f50.png",
      "in_place": false,
      "popup": true,
      "scopes": []
    },
    {
      "id": "email",
      "kind": "email",
      "name": "Email",
      "icon": null,
      "in_place": true,
      "popup": false,
      "scopes": []
    }
  ],
  "show_last_used": true
}
FieldWhat it is
idWhat synq_method (and the SDKs' signIn({ method })) takes: google, wallet, email…
kindprovider, wallet, email, password or passkey. More may come.
nameIts name, as people know it.
iconA provider's official mark on the issuer, where Synq has one: a 40 px PNG for a 20 px slot. Google's, Microsoft's and Telegram's are in their own colors, which you show as they are; the others (Apple, X, GitHub, Discord, Facebook, Matrica) are a white one-color mark: show it in an <img> and tint it with a CSS filter (filter: invert(1) turns it dark on a light panel). Not as a CSS mask-image, which loads only with CORS, which the issuer's artwork doesn't send. null for the rest.
in_placeWhether it finishes on your app's own screens, with no navigation: an emailed code, a password, a passkey or a wallet's signature, for a first-party app with own-UI sign-in on (a passkey only where browsers let your origin use the brand's passkeys). Otherwise it goes to Synq.
popupWhether it signs in at another site, an upstream provider, so your app may open it in a popup window rather than leave its page.
scopesWhat signing in with it shares beyond who the person is, scope by scope with its plain words: the extra scopes the brand asks that provider for.
show_last_usedWhether the brand marks the way a browser last signed in, and puts it first. Turn it off where people share devices.

The issuer lets an answer be kept for a minute, so a way you turn off is gone from every panel within a minute. An unknown client_id, an app that publishes its own metadata document, or a machine app is invalid_client.

In React

useSignInMethods() from @synqauth/react reads the list through your route mount (GET /api/auth/sign-in/methods with @synqauth/nextjs, which asks the issuer as your app and keeps the answer a minute), once for every component:

'use client'

import { embeddedBrowser } from '@synqauth/js'
import { type SignInMethod, useAuth, useLastUsedMethod, useSignInMethods } from '@synqauth/react'

export function GuildSignIn() {
  const { data: methods } = useSignInMethods()
  const lastUsed = useLastUsedMethod()
  const { signIn } = useAuth()
  // Google refuses to sign anyone in inside another app's built-in browser.
  const inApp = embeddedBrowser() !== null
  return (
    <ul>
      {methods
        ?.filter((method) => !(inApp && method.id === 'google'))
        .map((method) => (
          <li key={method.id}>
            <button onClick={() => signIn({ method: method.id as SignInMethod })}>
              {method.icon ? <img src={method.icon} alt="" width={20} height={20} /> : null}
              Continue with {method.name}
              {lastUsed?.method === method.id ? <span> Last used</span> : null}
            </button>
          </li>
        ))}
    </ul>
  )
}

A method with in_place finishes on your page with useSignIn() or the parts of <SignInForm> (Sign in from your own UI). Any other goes to Synq with signIn({ method }), straight to that method's own step. From a server, or any framework, @synqauth/js's signInMethods({ issuer, clientId }) reads the same list, and embeddedBrowser(userAgent) reads a request's user agent: android-webview, ios-in-app, or null for a real browser.

How each sign-in went

Turn on Sign-in context on your app's page in the dashboard, or set sign_in_claims: true when you change the app. It is for your brand's own apps (first_party). Your app's ID tokens then say how each sign-in went: sign_in_method, sign_in_wallet (the address that signed and its wallet app) and new_user (Tokens and claims). @synqauth/nextjs does two things with them on its callback.

"Last used", on your own site

The route mount keeps the way this browser signed in, in a cookie on your app's own host: the method, and for a wallet the wallet app's name, never an address or who it was, so a shared laptop shows nobody's wallet. It lasts 400 days and survives signing out, so your signed-out panel can mark it. getSession() returns it as lastUsed, and useLastUsedMethod() answers it, { method: 'wallet', walletApp: 'Phantom' } say, or null. Where the brand turned "Last used" off (show_last_used), the route mount keeps nothing and forgets what it kept at the next sign-in, and useLastUsedMethod() answers null as soon as useSignInMethods() says so. It does the same for a method the brand no longer offers.

A new account, once

The route mount also keeps the sign-in that just finished, sealed and bound to the person, for five minutes. getSession() returns it as event, and useSignInEvent() answers it: id (that sign-in's own, random), isNewUser, method, wallet and at (when they signed in, in seconds since the epoch). Show a first-profile screen, or a welcome, then call consume(): the event is gone, here and on your server, so a reload doesn't show it again.

'use client'

import { useSignInEvent } from '@synqauth/react'

export function FirstVisit() {
  const event = useSignInEvent()
  if (!event?.isNewUser) return null
  return (
    <dialog open>
      <p>Welcome to Acme Guild. Pick a username to finish your profile.</p>
      <button onClick={event.consume}>Done</button>
    </dialog>
  )
}

new_user is true once, for the app the sign-in made the account in: a second app that signs the person in through the same session at the brand, or your app signing them in again within it, hears false. Without sign_in_claims, both lastUsed and event stay null. A server that answers the same routes as the route mount, without Next.js, deletes the event at DELETE /api/auth/session/event.

On this page