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.

Authentication by subject type#

Authentication is application code. 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 GetAuthorizationFilterAsync 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.