API Reference - SqlOS Docs

OAuth Endpoints

OAuth routes are mounted when you call app.MapSqlOS(); the default issuer path is {DashboardBasePath}/auth (for example /sqlos/auth).

Method	Endpoint	Description
GET	`/.well-known/oauth-authorization-server`	OAuth metadata
GET	`/.well-known/jwks.json`	Public keys for JWT validation
GET	`/authorize`	OAuth authorize (PKCE)
POST	`/token`	Token exchange (code or refresh)
GET	`/login`	Hosted login page
GET	`/signup`	Hosted signup page

Auth API (Example)

The example API wraps SqlOS services into REST endpoints. Copy or adapt these patterns.

Discover

curl -X POST http://localhost:5062/api/v1/auth/discover \
  -H "Content-Type: application/json" \
  -d '{"email": "user@acme.com"}'

{"mode": "password", "organizations": []}

Login

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
}

Select Organization

curl -X POST http://localhost:5062/api/v1/auth/select-organization \
  -H "Content-Type: application/json" \
  -d '{"pendingAuthToken": "...", "organizationId": "org_..."}'

Refresh

curl -X POST http://localhost:5062/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "rt_...", "organizationId": null}'

Session

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

Logout

curl -X POST http://localhost:5062/api/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "rt_..."}'

OIDC Providers

curl http://localhost:5062/api/v1/auth/oidc/providers

[{"connectionId": "oidc_...", "providerType": "google", "displayName": "Google"}]

Start SSO

curl -X POST http://localhost:5062/api/v1/auth/sso/start \
  -H "Content-Type: application/json" \
  -d '{"email": "user@acme.com"}'

Dashboard Admin API

Used by the dashboard UI. Base path: /sqlos/admin/auth/api.

Organizations

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

Users

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

Memberships

curl -X POST http://localhost:5062/sqlos/admin/auth/api/memberships \
  -d '{"organizationId": "org_...", "userId": "usr_...", "role": "admin"}'

Clients

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

Security Settings

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

Sessions

curl http://localhost:5062/sqlos/admin/auth/api/sessions

FGA Admin API

Base path: /sqlos/admin/fga/api.

Resources

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

Grants

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

Access Test

curl -X POST http://localhost:5062/sqlos/admin/fga/api/access-test \
  -d '{"subjectId": "usr_...", "resourceId": "chain-1", "permissionKey": "CHAIN_VIEW"}'

{"allowed": true}

Roles and Permissions

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/subjects

Swagger

Open http://localhost:5062/swagger for the interactive API explorer when running the example stack.