FGA API Reference

This page documents the application-facing FGA surface. The recommended path is SqlOSDbContext<TContext> plus ISqlOSResourceEntity for protected domain rows, explicit subject provisioning, and explicit role grants. Public schema/bootstrap implementation classes are not intended as normal application extension points.

ISqlOSFgaAuthService#

The core authorization service. Injected via DI as ISqlOSFgaAuthService.

CheckAccessAsync#

Check if a subject has access to a specific resource with a given permission. Walks up the resource hierarchy from the target resource to the root, looking for grants whose role includes the required permission.

var access = await authService.CheckAccessAsync(subjectId, "CHAIN_VIEW", "chain-1");
if (!access.Allowed)
    return Results.Json(new { error = "Permission denied" }, statusCode: 403);

Parameters

Returns

Task<SqlOSFgaAccessCheckResult>

HasCapabilityAsync#

Check whether a subject has a permission on the configured FGA root resource. Use it for an intentionally global capability granted at root; it does not scan for the permission on arbitrary descendants.

var canEdit = await authService.HasCapabilityAsync(subjectId, "CHAIN_EDIT");
if (!canEdit)
    return Results.Json(new { error = "Permission denied" }, statusCode: 403);

Parameters

Returns

Task<bool> — the result of CheckAccessAsync(subjectId, permissionKey, RootResourceId).

GetAuthorizationFilterAsync#

Produce a LINQ expression that filters an IQueryable<T> to only entities the subject can access. The expression translates to a SQL Server table-valued function call at query time.

var filter = await authService
    .GetAuthorizationFilterAsync<Chain>(subjectId, "CHAIN_VIEW");
 
var chains = await dbContext.Chains
    .Where(filter)
    .OrderBy(c => c.Name)
    .ToListAsync();

Parameters

Type constraint: T : IHasResourceId — the entity must expose a ResourceId property. Protected domain entities should usually implement ISqlOSResourceEntity, which extends IHasResourceId and lets SqlOSDbContext<TContext> sync backing resource rows during EF saves.

Returns

Task<Expression<Func<T, bool>>> — an EF Core-compatible expression you pass to .Where().

Lifecycle enforcement#

Point checks, traces, and EF authorization filters apply the same lifecycle rules automatically. Inactive users and groups, expired service accounts, inactive target resources, and resources below an inactive ancestor are denied even when a matching grant remains stored. Applications do not need to revoke every grant when deactivating one of these records, and should not add a separate display-only lifecycle filter around authorization queries.

Provision typed subjects with the SDK helpers rather than inserting only a bare SqlOSFgaSubject: authorization fails closed when a user, group, agent, or service_account subject is missing its corresponding typed lifecycle row.

TraceResourceAccessAsync#

Produce a detailed, structured trace of a resource access decision. Shows every step of the hierarchy walk and which grants matched or didn't. Useful for debugging authorization issues.

var trace = await authService.TraceResourceAccessAsync(
    subjectId, "chain-1", "CHAIN_VIEW");
// trace contains the full decision path

Parameters

Returns

Task<SqlOSFgaResourceAccessTrace> — structured trace of the full decision.

SqlOS.Extensions#

Canonical SDK helpers for resource lifecycle, subject provisioning, and role grants. Available via using SqlOS.Extensions.

Resource Lifecycle APIs#

For protected application rows, implement ISqlOSResourceEntity and let SqlOSDbContext<TContext> synchronize SqlOSFgaResource rows during SaveChanges / SaveChangesAsync.

public sealed class Workspace : ISqlOSResourceEntity
{
    public Guid Id { get; set; }
    public string ResourceId { get; set; } = "";
    public string OrganizationId { get; set; } = "";
    public string Name { get; set; } = "";
 
    public string ResourceTypeId => "workspace";
    public string ResourceName => Name;
    public string ParentResourceId => $"org::{OrganizationId}";
    public string? ResourceDescription => null;
    public bool ResourceIsActive => true;
}

Manual resource APIs remain available for resources that are not backed by domain entities:

Subject and Grant APIs#

Subjects are provisioned explicitly. Grants never create subjects implicitly.

SqlOS.Fga.Extensions#

Lower-level/read-side FGA convenience extensions. Available via using SqlOS.Fga.Extensions.

CreateResource#

CreateResource(...) is a lower-level/manual lifecycle helper kept for manual FGA samples and existing code. Do not use it as the normal protected-entity creation path. For protected application rows, prefer ISqlOSResourceEntity plus SqlOSDbContext<TContext>.

// Manual lifecycle sample only.
var resourceId = context.CreateResource("retail_root", request.Name, "chain");

AuthorizedDetailAsync#

Fetch a single entity by predicate, check authorization, and return the appropriate HTTP result in one call. Replaces the pattern of fetch → check → map → return.

return await authService.AuthorizedDetailAsync(
    context.Chains.Include(c => c.Locations),
    c => c.Id == id,
    subjectId,
    "CHAIN_VIEW",
    chain => new ChainDetailDto
    {
        Id = chain.Id,
        Name = chain.Name,
        LocationCount = chain.Locations.Count
    });

Parameters

Type constraint: TEntity : class, IHasResourceId

Returns

Task<IResult> — one of:

PagedSpec Builder#

Fluent builder for creating cursor-paginated, sorted, searchable, authorization-filtered queries.

PagedSpec.For#

Start building a paged specification. The idSelector identifies the unique tiebreaker column for cursor pagination.

var spec = PagedSpec.For<Chain>(c => c.Id)
    .RequirePermission("CHAIN_VIEW")
    .SortByString("name", c => c.Name, isDefault: true)
    .SortByString("description", c => c.Description ?? "")
    .Search(search, c => c.Name, c => c.Description)
    .Configure(q => q.Include(c => c.Locations))
    .Build(pageSize, cursor, sortBy, sortDir);

Builder Methods

The exact query-configuration signature is:

public PagedSpecificationBuilder<T> Configure(
    Func<IQueryable<T>, IQueryable<T>> configurator)

The function must return the query it configures. An Action<IQueryable<T>> is not accepted.

ISpecificationExecutor#

Executes a PagedSpecification<T> against a queryable, combining user filters with FGA authorization and cursor pagination. Injected via DI.

ExecuteAsync#

Execute a paged specification and return a paginated result.

var result = await executor.ExecuteAsync(
    context.Chains, spec, subjectId,
    c => new ChainDto
    {
        Id = c.Id,
        Name = c.Name,
        LocationCount = c.Locations.Count
    });
 
// result.Data        — the page of DTOs
// result.PageSize    — the clamped page size used
// result.NextCursor  — pass to the next request
// result.HasNextPage — whether NextCursor is non-null

Parameters

Type constraint: TEntity : class, IHasResourceId

Returns

Task<PaginatedResult<TDto>>

CountAsync#

Count total matching entities (with authorization filtering) without fetching data.

var total = await executor.CountAsync(context.Chains, spec, subjectId);

Parameters

Returns

Task<long> — total count of accessible, matching entities.

ISqlOSResourceEntity#

Recommended resource lifecycle contract for protected application rows. It extends IHasResourceId and gives SqlOSDbContext<TContext> enough metadata to create, update, and delete backing FGA resources during EF saves.

public interface ISqlOSResourceEntity : IHasResourceId
{
    string ResourceTypeId { get; }
    string ResourceName { get; }
    string? ParentResourceId { get; }
    string? ResourceDescription { get; }
    bool ResourceIsActive { get; }
}

IHasResourceId#

Lower-level filter contract that exposes an entity's FGA resource ID. Required for GetAuthorizationFilterAsync, AuthorizedDetailAsync, and ISpecificationExecutor. ISqlOSResourceEntity extends this interface and is the recommended contract for normal protected domain rows.

public interface IHasResourceId
{
    string ResourceId { get; }
}

Lower-level implementation

public class Chain : IHasResourceId
{
    public string Id { get; set; } = Guid.NewGuid().ToString();
    public string ResourceId { get; set; } = "";
    public string Name { get; set; } = "";
}

FGA Models#

SqlOSFgaAccessCheckResult#

public class SqlOSFgaAccessCheckResult
{
    public bool Allowed { get; set; }
    public List<SqlOSFgaAccessTrace>? Trace { get; set; }
    public string? Error { get; set; }
}

SqlOSFgaAccessTrace#

public class SqlOSFgaAccessTrace
{
    public string Step { get; set; }
    public string Detail { get; set; }
    public string? ResourceId { get; set; }
    public string? ResourceName { get; set; }
    public string? GrantId { get; set; }
    public string? RoleName { get; set; }
    public string? SubjectName { get; set; }
}

SqlOSFgaResource#

public class SqlOSFgaResource
{
    public string Id { get; set; }
    public string ParentId { get; set; }
    public string Name { get; set; }
    public string ResourceTypeId { get; set; }
    public bool IsActive { get; set; }
}

SqlOSFgaGrant#

public class SqlOSFgaGrant
{
    public string Id { get; set; }
    public string SubjectId { get; set; }
    public string ResourceId { get; set; }
    public string RoleId { get; set; }
    public string? Description { get; set; }
}

SqlOSFgaSubject#

public class SqlOSFgaSubject
{
    public string Id { get; set; }
    public string SubjectTypeId { get; set; }
    public string DisplayName { get; set; }
    public string? OrganizationId { get; set; }
    public string? ExternalRef { get; set; }
}