Example applications

Choose by the result you need#

Single application: Notes#

The Notes sample is the complete UseSingleApplication example. Supply a SQL Server or PostgreSQL connection as described in its README, then run:

dotnet run --project examples/SqlOS.OneCall.Api

Open http://localhost:5085, sign in through AuthPage, and add a note. Connect an MCP client to /mcp to access the same notebook. Api, Mcp, Brand, and Authorization describe the host; its API and tools call the same FGA-enforcing service. The walkthrough includes another user's isolation, revocation, restoration, and logout.

Path 1: the .NET-first stack#

Run one command from the repository root:

dotnet run --project examples/SqlOS.Todo.AppHost/SqlOS.Todo.AppHost.csproj

This starts a persistent PostgreSQL container, the Todo API and embedded SqlOS host at http://localhost:5080, and the Razor Pages client at http://localhost:5090. Set SqlOS:DatabaseProvider=SqlServer to start SQL Server instead. Aspire reports resource health at its authenticated https://localhost:18890 dashboard.

The browser journey is deliberately ordinary ASP.NET Core:

1. the application issues an authentication challenge;
2. the OpenID Connect handler reads SqlOS discovery, then creates protected state, a correlation cookie, a nonce, and PKCE material;
3. SqlOS hosts user and organization sign-in;
4. middleware owns the /signin-sqlos callback, code exchange, ID token validation, and UserInfo claims;
5. the application calls protected /api/me and creates its encrypted cookie;
6. logout revokes the remote refresh token and session, then removes the local cookie.

Read the ASP.NET Core sample guide on GitHub for the source tour, security decisions, and troubleshooting.

Path 2: compare application architectures#

The full stack adds the broader example API, Next.js, and Angular:

npm ci --prefix packages/headless && npm run build --prefix packages/headless
npm ci --prefix examples/SqlOS.Example.Web
npm ci --prefix examples/SqlOS.Example.AngularWeb
dotnet run --project examples/SqlOS.Example.AppHost/SqlOS.Example.AppHost.csproj

Use it to compare a server-rendered .NET client with hosted and headless browser flows, optional social/OTP providers, multi-client registration, retail resource hierarchies, and identity-dependent EF results.

For the source-guided browser implementation, follow Build your own login and signup UI, then compare its focused flow with the complete Next.js and Angular clients below.

The AppHost starts these user-facing surfaces:

The authenticated Aspire dashboard URL is printed at startup; its configured listener is https://localhost:18888.

Application API coverage#

Retail retains its public demo/auth routes and additional demo credential types. Todo retains its configurable resource audience and per-operation scope checks. Notes demonstrates derived bearer-only API/MCP protection. The browser and native clients continue using their standard OIDC libraries with hosted AuthPage or @sqlos/headless.

Complete catalog#

The root example catalog documents every project, port, provider setting, persistence rule, and test command.

What the examples intentionally do not hide#

• Password sign-in works without a third-party provider. Email, phone, social, and calendar flows require the provider settings named in each README.
• AppHost SQL data persists between runs. A stale user, client, or grant may be database state rather than a seeding failure.
• The ASP.NET Core sample stores tokens in its encrypted authentication ticket for teaching clarity; larger deployments should consider a server-side ITicketStore.
• Expo is not launched by Aspire and needs simulator/device callback and network configuration.
• Backend protocol and authorization paths have real-SQL integration tests. The JavaScript client builds are checked, but the repository does not currently claim browser-automation coverage for every frontend journey.

Those boundaries are part of the reference implementation. They tell you which code is a trustworthy integration contract and which choices you still need to make for your own deployment.

Verify before you copy#

dotnet build SqlOS.sln
dotnet test examples/SqlOS.Example.Tests/SqlOS.Example.Tests.csproj
dotnet test examples/SqlOS.Todo.IntegrationTests/SqlOS.Todo.IntegrationTests.csproj
dotnet test examples/SqlOS.Example.IntegrationTests/SqlOS.Example.IntegrationTests.csproj

Continue with production readiness before adapting a local callback, cookie, secret, key ring, or persistent sample database to a deployed environment.