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
}| Field | What it is |
|---|---|
id | What synq_method (and the SDKs' signIn({ method })) takes: google, wallet, email… |
kind | provider, wallet, email, password or passkey. More may come. |
name | Its name, as people know it. |
icon | A 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_place | Whether 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. |
popup | Whether it signs in at another site, an upstream provider, so your app may open it in a popup window rather than leave its page. |
scopes | What 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_used | Whether 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.
Sign in from your own UI
Sign people in with a password, an emailed code, a passkey or a Solana wallet on your app's own screens, without sending them to the hosted page.
Add an account panel
Drop one component into your header for sign-in, a first sign-in's welcome and the profile, in a popover on a laptop and a sheet on a phone.