Subject Types

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

Subject types

Type	Entity	Use case
user	SqlOSFgaUser	Human users (synced from AuthServer)
agent	SqlOSFgaAgent	AI agents, bots, automated processes
service_account	SqlOSFgaServiceAccount	API keys for service-to-service access
user_group	SqlOSFgaUserGroup	Logical groups of users

Create a subject

Users are typically synced from AuthServer on login (see Syncing Auth to FGA):

context.Set<SqlOSFgaSubject>().Add(new SqlOSFgaSubject
{
    Id = user.Id,
    SubjectTypeId = "user",
    DisplayName = user.DisplayName,
    OrganizationId = organizationId,
    ExternalRef = user.Id
});

Agents and service accounts can be created through the dashboard or seeded in startup:

context.Set<SqlOSFgaSubject>().Add(new SqlOSFgaSubject
{
    Id = "inventory_sync_agent",
    SubjectTypeId = "agent",
    DisplayName = "Inventory Sync Agent"
});

Authentication by subject type

The example app supports multiple auth methods that map to different subject types:

public static string? GetSubjectId(this HttpContext http)
{
    // Bearer JWT → user subject
    var auth = http.Request.Headers.Authorization.ToString();
    if (auth.StartsWith("Bearer "))
        return ValidateAndGetUserId(auth);

    // X-Api-Key → service account subject
    if (http.Request.Headers.TryGetValue("X-Api-Key", out var apiKey))
        return apiKey.ToString();

    // X-Agent-Token → agent subject
    if (http.Request.Headers.TryGetValue("X-Agent-Token", out var agent))
        return agent.ToString();

    return null;
}

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

Dashboard

Manage subjects under Fine-Grained Auth > Users / Agents / Service Accounts / User Groups.