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>(...) 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. The SqlOS startup filter maps AuthServer, audit, email, and—when enabled—calendar endpoints into the application's route table. 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. Both documents always advertise response_modes_supported as ["query"] — SqlOS returns every authorization response in the redirect query string, never the fragment — and always advertise request_parameter_supported and request_uri_parameter_supported as false, because SqlOS does not accept request objects and the discovery default for request_uri_parameter_supported would otherwise claim it does. While OpenID Provider mode is enabled, both discovery documents also carry userinfo_endpoint, subject_types_supported (["public"]), id_token_signing_alg_values_supported (["RS256"]), and claims_supported.

scopes_supported is the sorted union of the scopes that at least one registered client can be granted, merged — while OpenID Provider mode is enabled (the default) — with the reserved OpenID Connect names openid, profile, and email. With the provider enabled, those three names are therefore always advertised, even in a deployment with no clients; only with the provider disabled does a zero-client deployment advertise an empty list. offline_access remains unadvertised because SqlOS does not gate refresh-token issuance on it — refresh tokens are always issued for code-flow clients — though it stays allowlistable for gateway compatibility. The list never includes internal auth:* credential-type strings. Requested scopes outside a client's allowlist are accepted by silent intersection. Operator-defined API scopes such as x.read appear when a client allowlist includes them.

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 when the request sent one, and the granted scope when that grant is non-empty. The scope query parameter is an intentional SqlOS extension: RFC 6749 §4.1.2 permits extra parameters, and clients can read the actual grant before exchanging the code. 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=...'

Public refresh — client_id is optional because the refresh token already names the client:

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 'refresh_token=...'

Confidential refresh still authenticates the client with its registered method. For client_secret_basic:

curl -X POST https://app.example.com/sqlos/auth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'billing-server:$CLIENT_SECRET' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=...'

Successful token responses use OAuth-style snake-case JSON fields such as access_token, refresh_token, token_type, expires_in, and scope. scope is the granted set after the same silent intersection used by /authorize, device authorization, and client_credentials. An empty grant is returned as an empty string rather than invalid_scope. Refresh-token responses echo the scope originally granted to the session; for sessions created before SqlOS recorded granted scope, the scope field is omitted rather than misreported as empty. OAuth errors use an error code and may include error_description.

The response carries an id_token field only when OpenID Provider mode is enabled and the granted scope includes openid. That applies to the authorization-code, refresh (refresh-minted ID tokens carry no nonce), and device grants; client_credentials responses never include one. When no ID token is minted, the field is absent — never null.

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.

UserInfo#

Mapped while OpenID Provider mode and its EnableUserInfoEndpoint option are enabled (both default to on).

Authenticate with a SqlOS access token: an Authorization: Bearer header on either method, or an access_token form field on POST. The session's granted scope must include openid.

curl https://app.example.com/sqlos/auth/userinfo \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

A success response is a JSON claims document. sub is always present; the remaining claims follow the scope granted at authorization time:

Validation is session-aware, not just JWT validation: session revocation, idle or absolute expiry, and user or organization deactivation stop claim release immediately. Failures use RFC 6750 Bearer challenges:

• 401 with WWW-Authenticate: Bearer error="invalid_token", error_description="The access token is invalid, expired, or its session is no longer active." — bad, expired, or session-dead token;
• 403 with WWW-Authenticate: Bearer error="insufficient_scope", error_description="The access token was not granted the openid scope." — a live token whose grant omits openid;
• a bare 401 with WWW-Authenticate: Bearer when no token was presented at all.

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 are for a first-party host integration: 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.

The sign-in routes (signup, password, email code, magic link, organization selection, and the MFA challenge completions) return tokens in the response body, so there is no page where a consent screen could appear. They accept only first-party clients. Any other client, including DCR and CIMD clients, gets 400 with { "error": "invalid_client", "message": "..." } before SqlOS checks a credential, sends an email, or mints a session, and SqlOS records an oauth.direct_login.rejected audit event. Third-party clients use /authorize.

POST /token/refresh is a public-client compatibility route. It has no client-authentication channel, so it ignores any Authorization header or secret field. When the refresh token belongs to a confidential client, it returns 401 with { "error": "invalid_client", "error_description": "Client authentication failed." } before rotation. The token is not consumed, no cached grace-window response is released, and SqlOS records an oauth.client_authentication.failed audit event. Confidential clients refresh through POST /sqlos/auth/token with grant_type=refresh_token, the canonical refresh flow for every client. In-process SqlOSAuthService.RefreshAsync enforces the same rule and throws SqlOSClientAuthenticationException.

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.

Platform-admin consent administration#

The same authenticated dashboard admin API manages consent grants and scope display names.

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" }
  }'

prompt, nonce, maxAge, and invitationToken are also accepted as optional JSON fields with the same semantics as their /authorize query parameters. Headless /start never silently reuses an issuer session, so maxAge is not a re-challenge gate here; the value persists on the authorization request, and a positive maxAge is still enforced at code issuance when interstitials such as organization selection or MFA outlast it.

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 issuer 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#

/oidc/authorization-url and /oidc/exchange are the app-owned social provider chooser. Like the direct sign-in routes above, they return tokens without a consent screen and accept only first-party clients; any other client gets 400 invalid_client before SqlOS creates provider state. A third-party client offers social sign-in through /authorize, whose hosted or headless page shows the provider buttons and runs consent.

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, scope-ceiling, and policy constraints.

When AuthServer.ClientRegistration.Dcr.AllowedScopes is non-empty, it is the operator ceiling: requested scopes outside that set are invalid_client_metadata. When the ceiling list is empty, requested scopes are registered as-is, still bounded by MaxScopeCount (default 32) and MaxScopeLength (default 128). Exceeding those limits is a registration error.

Success returns 201 Created with SqlOSDynamicClientRegistrationResponse, including scope. 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, SqlOS 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 the SqlOS startup filter; 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 SqlOS:

• /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.