Application Access

Application access answers a different question than OAuth audience.

Two apps can mint tokens for the same API audience. Assignments decide whether a principal may use a specific app, with organization context applied when one is selected.

Access modes#

Explicit denied assignments take precedence over allowed assignments.

Code-first policy#

Declare reproducible application policy on the client seed. Stable assignment keys let SqlOS update or revoke only the rows owned by that source configuration.

auth.SeedClient(client =>
{
    client.ClientId = "customer-portal";
    client.Name = "Customer Portal";
    client.RedirectUris = ["https://portal.example.com/auth/callback"];
    client.AccessMode = SqlOSApplicationAccessModes.SelectedOrganizations;
    client.AssignOrganization(
        "northwind-access",
        "northwind", // stable organization ID or slug
        description: "Contracted customer");
});

Use AssignOrganization, AssignUser, AssignGroup, AssignRole, AssignServiceAccount, or AssignAgent. Referenced organizations and principals must already exist and be active; FGA startup seeds are applied before client policy. Invalid, cross-organization, duplicate-key, and mode-incompatible assignments stop startup without opening access.

Code-owned access modes and assignments are visible but read-only in the dashboard. Emergency client disablement remains available. Dashboard-owned assignments may coexist as operator exceptions and are never deleted by seed reconciliation.

Admin API#

Set an application access mode:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/applications/{applicationId}/access-mode \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H "Content-Type: application/json" \
  -d '{ "accessMode": "selected_organizations" }'

Assign an organization:

curl -X POST http://localhost:5062/sqlos/admin/auth/api/applications/{applicationId}/assignments \
  -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  -H "Content-Type: application/json" \
  -d '{
    "principalType": "organization",
    "organizationId": "org_123",
    "access": "allowed",
    "reason": "Customer portal pilot"
  }'

Assign a user:

{
  "principalType": "user",
  "principalId": "usr_123",
  "access": "allowed"
}

Assign a group:

{
  "principalType": "group",
  "principalId": "grp_support",
  "access": "allowed"
}

Assign an organization role:

{
  "principalType": "role",
  "organizationId": "org_123",
  "roleKey": "admin",
  "access": "allowed"
}

Explain a decision:

curl -b "$SQLOS_DASHBOARD_COOKIE_JAR" \
  "http://localhost:5062/sqlos/admin/auth/api/applications/{applicationId}/access/check?organizationId=org_123&userId=usr_123"

The response includes allowed, decision, accessMode, source, assignmentId, and reason. It is intended for admin support and debugging, not public login pages.

These endpoints require an operator session; see Authenticate operator API calls.

Enforcement#

SqlOS checks application access when a concrete application and authenticated principal context are known, including organization context when one is selected:

• hosted authorization before issuing an auth code
• headless authorization before issuing an auth code
• Email OTP and signup token issuance through the shared session path
• SAML and OIDC callbacks before issuing an auth code
• device authorization approval before marking the request approved
• refresh token rotation before minting a new access token

Refresh uses the original session application and organization binding. If the app is disabled or the relevant assignment is revoked, refresh fails and an audit event is written.

Public failures use the generic message Application access is not allowed. so login pages do not reveal whether a user, organization, or assignment exists.

Audit#

SqlOS writes audit events for:

• application.access_mode.changed
• application.assignment.created
• application.assignment.revoked
• application.access.authorization_denied
• application.access.device_denied
• application.access.refresh_denied
• application.access.token_denied

Events include the client application ID, public client ID, user ID, organization ID where known, and decision metadata.

Dashboard#

Open Auth Server > Clients, inspect an application, then use the Access section to change access mode, create assignments, and revoke assignments.

Organization and user application availability is available through:

• GET /sqlos/admin/auth/api/organizations/{organizationId}/applications
• GET /sqlos/admin/auth/api/users/{userId}/applications

Single-app projects can stay on all_organizations until they need narrower app availability.

For the product framing behind this model, read Application Assignments: The Missing Layer Between Clients and Audiences.