Access Checks | SqlOS Docs

Use CheckAccessAsync for a yes/no answer: can this subject perform this action on this resource?

Authenticate before you authorize

FGA checks a subject ID; it does not validate bearer tokens. Protect the route group for this API's exact audience first, then derive the subject ID from GetSqlOSValidatedToken(). Never trust a subject ID supplied by the client.

CheckAccessAsync#

CSHARP

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

Use this for:

Mutations -- check before creating, updating, or deleting.
Single-resource gates -- when you already have the resource ID.

HasCapabilityAsync#

Check if a subject has a permission on the configured root resource:

CSHARP

var canManageWorkspaces = await authService.HasCapabilityAsync(subjectId, "WORKSPACE_MANAGE");

Use this for:

Global UI toggles -- show a create action backed by a root-level grant.
Platform gates -- enforce capabilities intentionally assigned at the root.

This method calls CheckAccessAsync for RootResourceId; it does not scan descendant resources to answer whether the subject has that permission somewhere.

Access Tester (dashboard)#

Test access decisions visually in the dashboard at Fine-Grained Auth > Access Tester.

Access Tester

Select a subject, permission, and resource to see whether access is allowed and trace the decision path.

Full mutation example#

Create a protected entity after checking access to its parent resource. SqlOSDbContext<TContext> syncs the backing FGA resource row when the entity is saved.

CSHARP

using SqlOS.AuthServer.Extensions;
using SqlOS.Extensions;
 
const string apiAudience = "https://api.acme.test";
 
var api = app.MapGroup("/api")
    .RequireSqlOSAccessToken(apiAudience);
 
api.MapPost("/workspaces", async (
    CreateWorkspaceRequest request,
    AppDbContext db,
    ISqlOSFgaAuthService authService,
    HttpContext http,
    CancellationToken ct) =>
{
    var subjectId = http.GetSqlOSValidatedToken()?.UserId;
    if (string.IsNullOrWhiteSpace(subjectId))
        return Results.Unauthorized();
 
    var organizationResourceId = $"org::{request.OrganizationId}";
 
    var access = await authService.CheckAccessAsync(
        subjectId,
        "WORKSPACE_MANAGE",
        organizationResourceId);
    if (!access.Allowed)
        return Results.Json(new { error = "Permission denied" }, statusCode: 403);
 
    var workspaceId = Guid.NewGuid();
    var workspace = new Workspace
    {
        Id = workspaceId,
        ResourceId = $"workspace::{workspaceId:D}",
        OrganizationId = request.OrganizationId,
        Name = request.Name.Trim()
    };
 
    db.Workspaces.Add(workspace);
    await db.SaveChangesAsync(ct);
 
    return Results.Created($"/api/workspaces/{workspace.Id}", workspace);
});

CheckAccessAsync#

CSHARP

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

Use this for:

Mutations -- check before creating, updating, or deleting.

Single-resource gates -- when you already have the resource ID.

HasCapabilityAsync#

Check if a subject has a permission on the configured root resource:

CSHARP

var canManageWorkspaces = await authService.HasCapabilityAsync(subjectId, "WORKSPACE_MANAGE");

Use this for:

Global UI toggles -- show a create action backed by a root-level grant.

Platform gates -- enforce capabilities intentionally assigned at the root.

This method calls CheckAccessAsync for RootResourceId; it does not scan descendant resources to answer whether the subject has that permission somewhere.

Full mutation example#

Create a protected entity after checking access to its parent resource. SqlOSDbContext<TContext> syncs the backing FGA resource row when the entity is saved.

CSHARP

using SqlOS.AuthServer.Extensions;
using SqlOS.Extensions;
 
const string apiAudience = "https://api.acme.test";
 
var api = app.MapGroup("/api")
    .RequireSqlOSAccessToken(apiAudience);
 
api.MapPost("/workspaces", async (
    CreateWorkspaceRequest request,
    AppDbContext db,
    ISqlOSFgaAuthService authService,
    HttpContext http,
    CancellationToken ct) =>
{
    var subjectId = http.GetSqlOSValidatedToken()?.UserId;
    if (string.IsNullOrWhiteSpace(subjectId))
        return Results.Unauthorized();
 
    var organizationResourceId = $"org::{request.OrganizationId}";
 
    var access = await authService.CheckAccessAsync(
        subjectId,
        "WORKSPACE_MANAGE",
        organizationResourceId);
    if (!access.Allowed)
        return Results.Json(new { error = "Permission denied" }, statusCode: 403);
 
    var workspaceId = Guid.NewGuid();
    var workspace = new Workspace
    {
        Id = workspaceId,
        ResourceId = $"workspace::{workspaceId:D}",
        OrganizationId = request.OrganizationId,
        Name = request.Name.Trim()
    };
 
    db.Workspaces.Add(workspace);
    await db.SaveChangesAsync(ct);
 
    return Results.Created($"/api/workspaces/{workspace.Id}", workspace);
});