Getting Started

The standard flow: one app, one call#

For a typical .NET B2B SaaS product you have one ASP.NET Core host, one EF Core DbContext on SQL Server or PostgreSQL, and one product that users sign in to. builder.AddSqlOS<TContext>(…) describes that product once and SqlOS derives the protocol consequences — auth routes, JWT schemes, metadata documents, client registration, seeds. Lock application APIs with RequireAuthorization(). If you expose MCP, set app.Mcp and map Microsoft's SDK yourself.

builder.AddSqlOS<AppDbContext>(
    db => db.UseSqlServer(connectionString),                   // or db.UseNpgsql(connectionString)
    options =>
    {
        options.UseSingleApplication("Acme", app =>
        {
            app.Origin = publicOrigin;                            // everything else derives from this
            app.Api = "/api";                                     // resource id {Origin}/api — scheme audience + PRM
            app.Mcp = "/mcp";                                      // resource id {Origin}/mcp — map the MCP SDK yourself
            app.Brand(page => page.PrimaryColor = "#0f172a");     // hosted sign-in colors, logo, copy
            // app.Headless("/auth/authorize");                   // ...or your own sign-in UI instead of the hosted pages
            app.Authorization(fga => fga                          // your permission model, reconciled at startup
                .ResourceType("project", "Project")
                .Permission("PROJECT_READ", "Read projects", "project")
                .Role("project_viewer", "Viewer").Can("PROJECT_READ"));
        });
 
        options.Dashboard.AuthMode = SqlOSDashboardAuthMode.Password;
        options.Dashboard.Password = dashboardPassword;
    });

Every line is optional except Origin. Start with Origin alone and add lines as the product needs them; nothing else changes.

Every option you need, on one screen#

Sign-in methods — passwords, email OTP, magic links, social login, SAML, MFA — are options.AuthServer seeds or dashboard settings, not code changes. Turn them on when you need them: Password · Email OTP · Social OIDC · SAML · MFA.

Hosted or headless: one line#

The hosted pages are the default and need nothing. When your product wants to own every screen, keep the same call and add one line:

app.Headless("/auth/authorize");   // your page at {Origin}/auth/authorize drives login, signup, OTP, MFA, consent

Your frontend then talks to a typed state machine (npm install @sqlos/headless) while SqlOS still owns OAuth, PKCE, sessions, and tokens. app.Brand(...) still applies; the headless view model exposes it. For full control over the redirect use app.Headless(headless => headless.BuildUiUrl = …). There is no separate dashboard toggle: BuildUiUrl present means headless. Build your own login UI · Hosted vs headless

Your front end (a browser SPA, a native app, or an agent) uses its standard OIDC client library to sign in as the derived client, with either hosted AuthPage or headless authentication UI, and calls /api with the resulting bearer token. AddSqlOS protects the endpoints you map under the declared surfaces; there is no middleware to place. See the complete Notes sample.

UseSingleApplication creates one first-party PKCE client, a callback at {Origin}/auth/callback, a default client allowlist (openid, profile, email, offline_access), and matching AuthPage branding. With OpenID Provider mode enabled (the default), authorization-server metadata advertises openid, profile, and email; offline_access stays on the client only for gateway compatibility and is not advertised, because SqlOS issues refresh tokens to code-flow clients without gating them on that scope. DCR stays off; CIMD and resource indicators turn on only when you declare Mcp.

Switch the EF callback to UseNpgsql(connectionString) to run the same host on PostgreSQL. See Choose SQL Server or PostgreSQL.

Pick your first result#

Adding SqlOS to your application is the canonical integration path; running the sample is the fastest evaluation. Do not begin with SAML, FGA modeling, CIMD, or DCR unless one of those is already a product requirement.

Second shape: many applications (identity provider)#

When other applications should sign in with your accounts — another browser application, a CLI alongside it, or a partner app using "Sign in with Acme" — the same host becomes an identity provider. Replace UseSingleApplication with ConfigureApplication to retain the host description, then declare each client explicitly with options.AuthServer.SeedClient(...) (or create them from the dashboard or admin API; all three share one validation and audit path). Everything from the standard flow still applies; you additionally get per-client consent, audiences, portable-client registration, and machine clients.

Runnable examples use this API: the retail stack serves Next.js, Angular, and Expo; the Todo stack serves Razor Pages and the CLI. A separate frontend and API can still be one client application; API/MCP resources do not themselves require additional browser-client registrations.

→ Multiple applications · Sign in with X · Clients

Add capabilities in this order#

What starts automatically#

When the host starts, SqlOS initializes and upgrades its own tables, automatically creates and protects a signing key when none exists, and applies settings and startup seeds. Your EF migrations continue to own your application tables. AddSqlOS also maps the OAuth, hosted login, and admin API routes and registers the dashboard middleware at startup.

Default paths:

Continue by job#

For the complete task directory, start at the documentation home. Use Example applications when you want a complete source path instead of an isolated integration step, and use the reference section after you know which service or endpoint you need.