HTTP API Reference

Choose the right surface#

SqlOS exposes several HTTP surfaces from the same package, but they are not interchangeable.

Base paths#

With the normal builder.AddSqlOS<TContext>(...) and app.MapSqlOS() setup, DashboardBasePath is the effective root. AddSqlOS derives the auth base as {DashboardBasePath}/auth after running the configuration callback. Setting AuthServer.BasePath independently inside that callback is therefore not an independent route-prefix override.

AuthServer.Issuer must be an absolute URI whose path matches the derived auth base. When PublicOrigin is configured, the issuer must be {PublicOrigin}{BasePath}.

The unified dashboard shell and the FGA component API/assets are middleware installed by AddSqlOS. FGA page routes are served by the unified shell; the FGA middleware does not expose a second dashboard document. MapSqlOS maps AuthServer, audit, email, and—when enabled—calendar endpoints. This distinction matters if you compose the ASP.NET Core pipeline manually.

OAuth discovery and keys#

Discovery is the authoritative source for endpoint URLs and advertised capabilities. Do not synthesize endpoint URLs in portable clients when discovery is available.

Authorization code and refresh tokens#

Authorization request#

SqlOS-specific presentation parameters include view (invite, login, signup, password, forgot-password, email-otp, phone-otp, or phone-otp-signup), ui_context for a headless UI, and invitation_token/invitationToken for an invitation-bound flow. Portable OAuth clients should rely only on discovery and standard parameters.

On success, SqlOS redirects to the exact registered redirect_uri with code, state, and the granted scope. Errors that occur after a valid authorization request can redirect to the client; malformed requests handled before that point render the hosted error page or redirect to the configured headless UI. Do not assume every /authorize failure has a JSON body.

Token request#

Authorization-code exchange:

curl -X POST https://app.example.com/sqlos/auth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=acme-web' \
  --data-urlencode 'code=...' \
  --data-urlencode 'redirect_uri=https://app.example.com/auth/callback' \
  --data-urlencode 'code_verifier=...'

Refresh:

curl -X POST https://app.example.com/sqlos/auth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=acme-web' \
  --data-urlencode 'refresh_token=...'

Successful token responses use OAuth-style snake-case JSON fields such as access_token, refresh_token, token_type, and expires_in. OAuth errors use an error code and may include error_description.

Device authorization#

Device authorization start uses form data:

curl -X POST https://app.example.com/sqlos/auth/device_authorization \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=acme-cli' \
  --data-urlencode 'scope=openid offline_access' \
  --data-urlencode 'resource=https://app.example.com/api'

Device authorization is enabled by default, but the client must explicitly allow the device grant. Seed it with SeedDeviceFlowClient/SeedCliClient or configure AllowDeviceAuthorization plus the device-code grant on the client.

A successful start response is:

{
  "device_code": "opaque-device-secret",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://app.example.com/sqlos/auth/device",
  "verification_uri_complete": "https://app.example.com/sqlos/auth/device?user_code=ABCD-EFGH",
  "expires_in": 900,
  "interval": 5
}

Honor interval while polling /token. Device errors use the OAuth-style error and error_description fields and can include an updated interval.

Hosted AuthPage#

These browser routes render or process the SqlOS-hosted sign-in experience. Applications normally begin at /authorize; they do not call each form handler directly. The form posts use application/x-www-form-urlencoded and can change with the bundled UI.

Every hosted POST requires the short-lived antiforgery field and matching browser cookie issued by a SqlOS GET page. The bundled UI supplies both automatically. Missing, expired, cross-browser, or cross-origin submissions return 400 before credentials or authorization state are processed. This requirement does not apply to the headless or direct JSON APIs.

Integrate through /authorize, /token, and the documented AuthPage configuration unless you are intentionally building a headless UI. POST /sqlos/auth/signup and POST /sqlos/auth/logout are JSON helpers described next; they are not hosted form handlers.

Direct JSON authentication API#

These routes expose the same strongly typed contracts used by SqlOSAuthService. They can be useful for a first-party host integration, but they are not a second OAuth protocol and they do not share one normalized error envelope. Some handlers return a plain 400 message while others allow service exceptions to flow through the host's exception pipeline.

POST /token/exchange consumes the temporary code created by the direct SAML request-token flow. An OAuth authorization-code client must use the form-encoded POST /token endpoint, which enforces the OAuth redirect URI, PKCE verifier, and optional resource binding.

Account-management routes are secure by default without adding a blanket ASP.NET Core authorization policy to /sqlos/auth. Logout accepts only refresh-token proof of session ownership; the HTTP route ignores a caller-supplied sessionId. Logout-all derives the user from an active, unconsumed refresh token and never accepts a userId. Email-verification requests send a one-time link through the configured SqlOS email pipeline, use the trusted PublicOrigin/issuer rather than request host headers, suppress rapid resends, and return the same public shape for known, unknown, already verified, and delivery-failure cases.

Trusted backend code can still call SqlOSAuthService.LogoutAsync(..., sessionId: ...), LogoutAllAsync(userId), or CreateEmailVerificationTokenAsync(...) after applying its own ownership/admin policy. Do not expose those service methods by mapping caller-supplied IDs or raw tokens directly into a public route.

Platform-admin session revocation#

The dashboard admin API has two authenticated platform-operator routes. Unauthorized requests receive the same not-found response used by the rest of the admin control plane.

Supply at least one of sessionId, userId, organizationId, or clientApplicationId. Multiple values are combined with AND semantics. For a broad operation, copy the preview's matchedSessions into expectedMatchedSessions; execution rejects a changed count so the operator must preview and confirm the current scope again. reason and operationId are bounded strings, operation IDs cannot be reused for a different selector/reason, and operations matching more than 10,000 sessions are rejected so callers must narrow the incident scope. The API returns a generic not-found result when execution matches no records and does not expose cross-tenant record details.

Headless AuthPage API#

The default headless base is /sqlos/auth/headless. It can be moved with AuthServer.Headless.HeadlessApiBasePath. AuthServer.Headless.EnableApi defaults to true; disabling it leaves the routes unavailable with 404. These endpoints use JSON and operate on SqlOS authorization-request state.

Start a flow with the same OAuth values you would send to /authorize:

curl -X POST https://app.example.com/sqlos/auth/headless/start \
  -H 'Content-Type: application/json' \
  -d '{
    "responseType": "code",
    "clientId": "acme-web",
    "redirectUri": "https://app.example.com/auth/callback",
    "state": "client-generated-state",
    "scope": "openid offline_access",
    "codeChallenge": "...",
    "codeChallengeMethod": "S256",
    "resource": "https://app.example.com/api",
    "loginHint": "jane@example.com",
    "view": "login",
    "uiContext": { "returnTo": "/settings" }
  }'

Actions return SqlOSHeadlessActionResult. This abridged response shows the control-flow fields:

{
  "type": "view",
  "redirectUrl": null,
  "viewModel": {
    "view": "login",
    "requestId": "req_...",
    "settings": {},
    "providers": [],
    "organizationSelection": []
  }
}

Keep requestId from the view model and send it in subsequent action requests. A completed action returns type: "redirect" with the registered client redirect URL; organization selection and MFA instead return another view. Validation failures currently use route-specific 400 bodies rather than one universal error object.

For browser clients on a different origin, send credentialed requests so the reusable AuthPage session cookie is preserved. The cookie is HttpOnly; the response view model and action result are the UI contract. See Build your own login and signup UI for the complete browser, PKCE, callback, CORS, and cookie walkthrough, or Headless Auth for feature details.

Social OIDC and SAML callbacks#

Prefer canonical /sqlos/auth/authorize plus /sqlos/auth/token over invoking callback routes manually. The SAML authorization helper requires state, codeChallenge, and codeChallengeMethod: "S256"; its code is exchanged only at the standard token endpoint with the exact redirect URI and verifier. The former /token/exchange and /saml/login/{connectionId} compatibility routes are not mapped.

Dynamic client registration#

POST /sqlos/auth/register is mapped only when AuthServer.ClientRegistration.Dcr.Enabled is true. It accepts a SqlOSDynamicClientRegistrationRequest JSON document and applies the configured DCR redirect, client-type, rate-limit, and policy constraints.

Success returns 201 Created with SqlOSDynamicClientRegistrationResponse. Rejections use { error, error_description } with the status selected by SqlOSClientRegistrationException. SqlOS does not implement an RFC 7592 client-management endpoint.

CIMD does not add a registration route. When enabled, SqlOS resolves URL-shaped client IDs through client metadata documents subject to its trust configuration. See Preregistration vs CIMD vs DCR.

Customer SSO setup portal#

Self-serve SAML setup has a narrower trust boundary than the full dashboard:

The portal API can configure only the session's organization and SAML connection; it is not a general admin API. For a product-owned backend, inject SqlOSSsoPortalService to create setup sessions and expose only the setup URL. See SAML SSO.

Calendar callback#

SqlOSOptions.Calendar.Enabled defaults to true. While enabled, MapSqlOS adds:

Applications start the flow through SqlOSCalendarService.StartConnectAsync; there is no public HTTP start endpoint supplied by the package.

The callback consumes the one-time state and redirects to the exact ReturnUri from SqlOSStartCalendarConnectRequest. Success appends calendarConnectionId; provider or completion failure appends error. Treat both values as callback input and verify the resulting connection belongs to the expected user or organization before using it.

Dashboard and operator APIs#

SqlOS also exposes APIs used by the embedded auth, FGA, audit, email, SSO-setup, and optional calendar dashboards. Endpoint groups are mapped by MapSqlOS; the unified shell and FGA component API/assets are middleware installed by AddSqlOS. These surfaces:

• are excluded from ApiExplorer/OpenAPI descriptions;
• are protected by the dashboard authorization/session rules, except delegated SSO setup routes that use their own one-time setup token and organization-scoped portal cookie;
• hide, reject, or redirect unauthorized requests according to dashboard auth mode and whether the request is an API or page;
• are implementation endpoints for the bundled operator UI, not a stable browser-facing management SDK.

For trusted backend administration, inject the corresponding .NET service (SqlOSAdminService, ISqlOSAuditLogService, SqlOSEmailAdminService, SqlOSCalendarService, or SqlOSSsoPortalService) rather than coupling application code to dashboard JSON shapes.

Use path-specific network/edge rules in production. Restrict the exact dashboard root (/sqlos or /sqlos/) and dashboard/operator paths under /sqlos/admin/*, but allow /sqlos/admin/auth/sso-portal* when customers use delegated SSO setup. Keep the /sqlos/auth/* routes required by hosted OAuth/authentication reachable; do not apply blanket /sqlos/* or /sqlos/admin/* blocks without those intentional exceptions.

Example-application routes are not package APIs#

Routes such as the following are defined under examples/ and are not mounted by MapSqlOS:

• /api/v1/auth/*
• /api/todos
• /api/sso-portal-links
• /sample/config
• /.well-known/oauth-protected-resource
• /swagger and /swagger/v1/swagger.json

They demonstrate how a consuming application can wrap SqlOS services, publish protected-resource metadata, or expose its own product API. Copy the pattern only after checking the example source against your authorization and trust boundary.

OpenAPI boundary#

Mapped SqlOS endpoint groups call ExcludeFromDescription(), while dashboard middleware is not an endpoint surface at all. A consuming app's Swagger/OpenAPI document therefore does not automatically become the canonical SqlOS protocol specification. Use OAuth discovery for machine-readable OAuth endpoint metadata and this source-aligned route reference for the remaining package routes. Swagger shown by the example stack describes the example application's endpoints, not the complete SqlOS package surface.