AuthServer
Clients
Choose the right client onboarding path for owned apps, portable clients, and compatibility clients.
A client is the app that sends a user into SqlOS sign in and later exchanges the auth code for tokens.
SqlOS now supports three client onboarding paths:
- Owned apps -- seeded or dashboard-created clients for your own web, mobile, desktop, or SPA apps
- CLI apps -- device-flow clients for terminal tools without redirect listeners
- Portable clients --
CIMDwhen theclient_idis a stable HTTPS metadata document - Compatibility clients -- optional
DCRfor public clients that still expect runtime registration
If you are unsure, start with the first path.
For a one-app setup, use Single-Application Setup before reaching for explicit client seeding.
Fastest path: owned app#
This is the default path for most teams.
Use it for:
- your own browser app
- your own mobile app
- your own desktop or local native app
- the first version of a hosted SqlOS setup
Dashboard#
Open Auth Server > Clients.
Startup seeding#
Recommended for first-party apps:
builder.AddSqlOS<AppDbContext>(options =>
{
options.AuthServer.SeedOwnedWebApp(
"my-web-app",
"My Web Application",
"http://localhost:3000/auth/callback",
"https://app.example.com/auth/callback");
});Admin API#
curl -X POST http://localhost:5062/sqlos/admin/auth/api/clients \
-H "Content-Type: application/json" \
-d '{
"clientId": "my-web-app",
"name": "My Web Application",
"audience": "sqlos",
"redirectUris": ["http://localhost:3000/auth/callback"]
}'| Field | Required | Description |
|---|---|---|
clientId | Yes | Unique identifier (e.g., my-web-app) |
name | Yes | Display name |
audience | No | Token audience claim |
redirectUris | Yes | Allowed callback URIs for OAuth flows |
CLI and terminal apps#
Use the CLI / Device OAuth dashboard preset or seed a CLI client:
builder.AddSqlOS<AppDbContext>(options =>
{
options.AuthServer.SeedCliClient(
"acme-cli",
"Acme CLI",
"https://api.acme.com",
"openid",
"profile",
"email",
"offline_access");
});CLI clients are public clients. They do not require redirect URIs and are allowed to use:
urn:ietf:params:oauth:grant-type:device_coderefresh_token
See CLI OAuth for the complete flow and polling rules.
Startup-managed vs dashboard-created#
Clients seeded in startup code are marked as startup managed. Their configuration is reapplied on every restart, so changes made in the dashboard will be overwritten.
Dashboard-created clients are fully editable and persist across restarts.
Portable clients with CIMD#
Use CIMD when a public client uses a stable HTTPS client_id that points to its own metadata document.
This is the better long-term public-client story because the client keeps its own metadata and SqlOS can fetch and cache it.
Enable it with:
builder.AddSqlOS<AppDbContext>(options =>
{
options.AuthServer.ClientRegistration.Cimd.Enabled = true;
});That path is especially useful for:
- portable MCP clients
- public clients shared across many servers
- clients that should not be hand-entered into every SqlOS deployment
Compatibility clients with DCR#
Use DCR only when a real client still expects runtime registration.
Enable it with:
builder.AddSqlOS<AppDbContext>(options =>
{
options.AuthServer.ClientRegistration.Dcr.Enabled = true;
});SqlOS keeps this path intentionally narrow in v1:
- public PKCE clients only
token_endpoint_auth_method=none- strict redirect validation
- rate limiting and audit logging
Multiple clients#
Register separate clients for each frontend. The example stack seeds three:
auth.SeedOwnedWebApp("example-web", "Example Web", "http://localhost:3010/auth/callback");
auth.SeedOwnedWebApp("example-angular", "Example Angular", "http://localhost:4200/auth/callback");
auth.SeedOwnedNativeApp("example-expo", "Example Expo", "sqlos-expo://auth-callback");