Subject Types

A subject is the entity being authorized. Every grant links a subject to a role on a resource.

Subject types#

Provision subjects#

Use the SDK provisioning helpers for users, agents, and service accounts. The app resolves the current subject ID at its own request boundary, then passes that explicit ID into FGA.

using SqlOS.Extensions;
 
await context.ProvisionUserSubjectAsync(
    subjectId,
    displayName: displayName,
    email: email,
    externalRef: subjectId,
    cancellationToken: ct);

Agents and service accounts use the same explicit provisioning shape:

await context.ProvisionAgentSubjectAsync(
    "inventory_sync_agent",
    displayName: "Inventory Sync Agent",
    externalRef: "inventory-sync",
    cancellationToken: ct);
 
await context.ProvisionServiceAccountSubjectAsync(
    "service_account::billing_api",
    displayName: "Billing API",
    clientId: "billing-api",
    clientSecretHash: storedSecretHash,
    description: "Billing API service account",
    cancellationToken: ct);

The helpers are idempotent and update provided mutable fields without creating grants. Grants stay explicit:

await context.GrantRoleAsync(
    subjectId,
    resourceId,
    "workspace_member",
    ct);

Groups#

Create groups and manage group membership through ISqlOSFgaSubjectService:

var group = await subjectService.CreateGroupAsync(
    "Inventory Operators",
    "People and agents that operate inventory workflows",
    cancellationToken: ct);
 
await subjectService.AddToGroupAsync(subjectId, group.Id, ct);

Groups are subjects with type group, but groups cannot be members of other groups.

For the complete membership, grant, inherited-access, and removal workflow, follow Authorize teams with FGA groups. That guide also explains why SqlOSFgaUserGroup.Id is used for membership while SubjectId is used for grants.

A service account is an FGA subject. It can receive grants without being an AuthServer user. It is not a machine client. A machine client is the AuthServer confidential OAuth client that exchanges a secret at /sqlos/auth/token. SeedMachineClient and Auth Server > Machine Clients can create both and link them; provisioning a service account here does not register that OAuth client. See Machine Clients.

Authentication by subject type#

Authentication is application code or AuthServer. A bearer token, API key, or agent token can map to a user, service account, or agent subject, but FGA receives only the resolved subjectId.

All subject types use the same FGA authorization -- the same CheckAccessAsync and BuildFilterAsync calls work regardless of whether the subject is a user, agent, service account, or group.

Dashboard#

Manage subjects under Fine-Grained Auth > Users / Agents / Service Accounts / User Groups. Create or rotate OAuth worker credentials under Auth Server > Machine Clients.