Reference
API Reference
HTTP endpoints for auth, admin, and FGA.
For the central governance event model, service APIs, dashboard filters, and CSV export limits, see Audit Logs Reference.
Call app.MapSqlOS() to mount OAuth. Default base: {DashboardBasePath}/auth (e.g. /sqlos/auth).
| Method | Endpoint | Description |
|---|---|---|
| GET | /sqlos/auth/.well-known/oauth-authorization-server | OAuth metadata |
| GET | /sqlos/auth/.well-known/jwks.json | Public keys for JWT validation |
| GET | /sqlos/auth/authorize | OAuth authorize (PKCE) |
| POST | /sqlos/auth/token | Token exchange (code or refresh) |
| GET | /sqlos/auth/login | Hosted login page |
| GET | /sqlos/auth/signup | Hosted signup page |
| POST | /sqlos/auth/mfa/challenge/verify | Verify TOTP or recovery code for a direct MFA challenge |
| POST | /sqlos/auth/mfa/challenge/totp/enroll/start | Start TOTP enrollment for a direct MFA challenge |
| POST | /sqlos/auth/mfa/challenge/totp/enroll/verify | Verify TOTP enrollment for a direct MFA challenge |
Base path: /sqlos/auth/headless.
| Method | Endpoint | Description |
|---|---|---|
| GET | /requests/{requestId} | Load the current authorization request view model |
| POST | /identify | Submit email for home realm discovery |
| POST | /password/login | Submit email and password |
| POST | /email-otp/start | Start email OTP sign-in |
| POST | /email-otp/verify | Verify email OTP sign-in |
| POST | /signup | Create a password user and complete authorization |
| POST | /signup/email-otp/start | Start passwordless signup |
| POST | /signup/email-otp/verify | Verify passwordless signup |
| POST | /organization/select | Select an organization after primary login |
| POST | /mfa/verify | Verify TOTP or recovery code |
| POST | /mfa/totp/enroll/start | Start forced TOTP enrollment |
| POST | /mfa/totp/enroll/verify | Verify forced TOTP enrollment and continue authorization |
The sample API exposes REST helpers around SqlOS. Copy the shape you need.
curl -X POST http://localhost:5062/api/v1/auth/discover \
-H "Content-Type: application/json" \
-d '{"email": "user@acme.com"}'{"mode": "password", "organizations": []}curl -X POST http://localhost:5062/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "admin@retail.demo", "password": "RetailDemo1!"}'{
"accessToken": "eyJhbG...",
"refreshToken": "rt_...",
"sessionId": "ses_...",
"organizationId": "org_...",
"requiresOrganizationSelection": false
}curl -X POST http://localhost:5062/api/v1/auth/select-organization \
-H "Content-Type: application/json" \
-d '{"pendingAuthToken": "...", "organizationId": "org_..."}'curl -X POST http://localhost:5062/api/v1/auth/refresh \
-H "Content-Type: application/json" \
-d '{"refreshToken": "rt_...", "organizationId": null}'curl http://localhost:5062/api/v1/auth/session \
-H "Authorization: Bearer eyJhbG..."{
"userId": "usr_...",
"sessionId": "ses_...",
"organizationId": "org_...",
"email": "admin@retail.demo",
"displayName": "Company Admin"
}curl -X POST http://localhost:5062/api/v1/auth/logout \
-H "Content-Type: application/json" \
-d '{"refreshToken": "rt_..."}'curl http://localhost:5062/api/v1/auth/oidc/providers[{"connectionId": "oidc_...", "providerType": "google", "displayName": "Google"}]curl -X POST http://localhost:5062/api/v1/auth/sso/start \
-H "Content-Type: application/json" \
-d '{"email": "user@acme.com"}'The example API demonstrates how a host app can launch the delegated org-admin portal for the current org_id instead of exposing the full dashboard admin API to its frontend.
curl -X POST http://localhost:5062/api/sso-portal-links \
-H "Authorization: Bearer eyJhbG..." \
-H "Content-Type: application/json" \
-d '{"provider": "microsoft-entra"}'{
"id": "ssp_...",
"organizationId": "org_...",
"status": "pending",
"setupUrl": "https://localhost/sqlos/admin/auth/sso-portal/start?token=..."
}Used by the dashboard UI. Base path: /sqlos/admin/auth/api.
# List
curl http://localhost:5062/sqlos/admin/auth/api/organizations
# Create
curl -X POST http://localhost:5062/sqlos/admin/auth/api/organizations \
-d '{"name": "Acme Corp", "slug": "acme", "primaryDomain": "acme.com"}'# List
curl http://localhost:5062/sqlos/admin/auth/api/users
# Create
curl -X POST http://localhost:5062/sqlos/admin/auth/api/users \
-d '{"displayName": "Jane Doe", "email": "jane@acme.com", "password": "secret123"}'curl -X POST http://localhost:5062/sqlos/admin/auth/api/memberships \
-d '{"organizationId": "org_...", "userId": "usr_...", "role": "admin"}'curl -X POST http://localhost:5062/sqlos/admin/auth/api/clients \
-d '{"clientId": "my-app", "name": "My App", "audience": "sqlos", "redirectUris": ["http://localhost:3000/callback"]}'# Get
curl http://localhost:5062/sqlos/admin/auth/api/settings/security
# Update
curl -X PUT http://localhost:5062/sqlos/admin/auth/api/settings/security \
-d '{"refreshTokenLifetimeMinutes": 10080, "sessionIdleTimeoutMinutes": 1440, "sessionAbsoluteLifetimeMinutes": 43200}'# Get global MFA settings
curl http://localhost:5062/sqlos/admin/auth/api/settings/mfa
# Update global MFA settings
curl -X PUT http://localhost:5062/sqlos/admin/auth/api/settings/mfa \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"totpEnabled": true,
"userSelfEnrollmentEnabled": true,
"recoveryCodesEnabled": true,
"requireForAllUsers": false,
"requireForOwnersAndAdmins": true,
"requiredRoles": ["owner", "admin"],
"availableFactors": ["totp", "recovery_code"]
}'
# Update one organization's MFA policy
curl -X PUT http://localhost:5062/sqlos/admin/auth/api/organizations/org_123/mfa-policy \
-H "Content-Type: application/json" \
-d '{
"isEnabled": true,
"requireMfaForAllUsers": true,
"requireMfaForOwnersAndAdmins": false,
"userSelfEnrollmentEnabled": true,
"recoveryCodesEnabled": true,
"requiredRoles": ["owner", "admin"],
"availableFactors": ["totp", "recovery_code"]
}'curl http://localhost:5062/sqlos/admin/auth/api/sessions# Create a one-organization setup link
curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-portal/sessions \
-H "Content-Type: application/json" \
-d '{"organizationId": "org_...", "provider": "okta"}'
# List setup links for an organization
curl http://localhost:5062/sqlos/admin/auth/api/organizations/org_.../sso-portal/sessions
# Revoke a setup link or opened portal session
curl -X POST http://localhost:5062/sqlos/admin/auth/api/sso-portal/sessions/ssp_.../revoke \
-H "Content-Type: application/json" \
-d '{"reason": "rotated"}'The setup URL opens /sqlos/admin/auth/sso-portal/start?token=.... The first open consumes the URL token and sets a server-side portal session cookie. Portal APIs under /sqlos/admin/auth/sso-portal/api require that cookie and are scoped to the linked organization:
| Method | Endpoint | Description |
|---|---|---|
| GET | /state | Organization, provider guides, SP values, connection status |
| PUT | /provider | Choose microsoft-entra, okta, google-workspace, or generic-saml |
| POST | /domain | Create or reuse a pending domain-ownership TXT record |
| POST | /domains/{domainId}/confirm | Verify DNS TXT ownership and activate the domain claim |
| POST | /metadata/validate | Validate pasted or uploaded metadata XML |
| POST | /metadata | Save metadata and hold the connection for activation |
| POST | /activate | Enable the SAML connection after review |
| POST | /disable | Disable the organization SAML connection |
| POST | /test | Validate readiness or create a SAML redirect when clientId and redirectUri are supplied |
| POST | /signout | Clear the portal session cookie |
The headless setup API defaults to /sqlos/admin/auth/sso-portal/api/setup, can be moved with SsoPortal.HeadlessApiBasePath, and returns SqlOSSsoSetupActionResult records for custom admin UIs:
| Method | Endpoint | Description |
|---|---|---|
| GET | / | Current setup view model |
| PUT | /provider | Select provider and advance to the domain step |
| POST | /domain | Start DNS TXT verification |
| POST | /domains/{domainId}/confirm | Confirm ownership |
| POST | /metadata/validate | Validate metadata XML |
| POST | /metadata | Import metadata and advance to activation |
| POST | /activate | Activate if allowed actions permit it |
| POST | /disable | Disable the connection |
| POST | /test | Run or record a readiness test |
| POST | /signout | Close the portal session |
The setup view model includes domain, serviceProvider, providers, latestTest, and allowedActions. Domain ownership uses a TXT record shaped like _sqlos-verify.acme.com = sqlos-domain-verification=... by default. Hosts can customize both prefixes with SsoPortal.DomainVerificationRecordPrefix and SsoPortal.DomainVerificationRecordValuePrefix.
Base path: /sqlos/admin/fga/api.
# List (tree)
curl http://localhost:5062/sqlos/admin/fga/api/resources
# Create
curl -X POST http://localhost:5062/sqlos/admin/fga/api/resources \
-d '{"name": "New Chain", "typeId": "chain", "parentId": "retail_root"}'# List
curl http://localhost:5062/sqlos/admin/fga/api/grants
# Create
curl -X POST http://localhost:5062/sqlos/admin/fga/api/grants \
-d '{"subjectId": "usr_...", "roleId": "role_...", "resourceId": "org::acme"}'
# Revoke
curl -X DELETE http://localhost:5062/sqlos/admin/fga/api/grants/{id}curl -X POST http://localhost:5062/sqlos/admin/fga/api/access-test \
-d '{"subjectId": "usr_...", "resourceId": "chain-1", "permissionKey": "CHAIN_VIEW"}'{"allowed": true}curl http://localhost:5062/sqlos/admin/fga/api/roles
curl http://localhost:5062/sqlos/admin/fga/api/permissions
curl http://localhost:5062/sqlos/admin/fga/api/subjectsOpen http://localhost:5062/swagger for the interactive API explorer when running the example stack.