Mutations | SqlOS Docs

For create, update, and delete operations, check authorization first with CheckAccessAsync, then mutate your EF entity. If the entity implements ISqlOSResourceEntity and the DbContext derives from SqlOSDbContext<TContext>, SqlOS keeps the backing FGA resource row synchronized when EF saves.

FGA authorizes a subject but does not authenticate the caller. Protect the API route group for its exact audience, and derive the subject from the SqlOS-validated token:

CSHARP

using SqlOS.AuthServer.Extensions;
using SqlOS.Extensions;
 
const string apiAudience = "https://api.acme.test";
 
var api = app.MapGroup("/api")
    .RequireSqlOSAccessToken(apiAudience);

All endpoints below are mapped on that protected api group. Do not accept subjectId from a request body, route value, or unvalidated JWT claim.

Create pattern#

Check permission on the parent resource.
Create the domain entity.
Assign a stable ResourceId before save.
Save the entity. SqlOS syncs the SqlOSFgaResource row in the same EF save.

CSHARP

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);
});

Update pattern#

CSHARP

api.MapPut("/workspaces/{id}", async (
    Guid id,
    UpdateWorkspaceRequest request,
    AppDbContext db,
    ISqlOSFgaAuthService authService,
    HttpContext http,
    CancellationToken ct) =>
{
    var subjectId = http.GetSqlOSValidatedToken()?.UserId;
    if (string.IsNullOrWhiteSpace(subjectId))
        return Results.Unauthorized();
 
    var workspace = await db.Workspaces.FindAsync([id], ct);
    if (workspace == null) return Results.NotFound();
 
    var access = await authService.CheckAccessAsync(
        subjectId,
        "WORKSPACE_MANAGE",
        workspace.ResourceId);
    if (!access.Allowed)
        return Results.Json(new { error = "Permission denied" }, statusCode: 403);
 
    workspace.Name = request.Name.Trim();
    await db.SaveChangesAsync(ct);
 
    return Results.Ok(workspace);
});

Because ResourceName => Name, the backing FGA resource display name updates with the entity.

Delete pattern#

CSHARP

api.MapDelete("/workspaces/{id}", async (
    Guid id,
    AppDbContext db,
    ISqlOSFgaAuthService authService,
    HttpContext http,
    CancellationToken ct) =>
{
    var subjectId = http.GetSqlOSValidatedToken()?.UserId;
    if (string.IsNullOrWhiteSpace(subjectId))
        return Results.Unauthorized();
 
    var workspace = await db.Workspaces.FindAsync([id], ct);
    if (workspace == null) return Results.NotFound();
 
    var access = await authService.CheckAccessAsync(
        subjectId,
        "WORKSPACE_MANAGE",
        workspace.ResourceId);
    if (!access.Allowed)
        return Results.Json(new { error = "Permission denied" }, statusCode: 403);
 
    db.Workspaces.Remove(workspace);
    await db.SaveChangesAsync(ct);
 
    return Results.NoContent();
});

Deletes remove the backing resource and direct grants. If child resources still reference the resource, SqlOS throws a clear exception so the application can delete or reparent children first.

Create pattern#

Check permission on the parent resource.

Create the domain entity.

Assign a stable ResourceId before save.

Save the entity. SqlOS syncs the SqlOSFgaResource row in the same EF save.

CSHARP

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);
});

Update pattern#

CSHARP

api.MapPut("/workspaces/{id}", async (
    Guid id,
    UpdateWorkspaceRequest request,
    AppDbContext db,
    ISqlOSFgaAuthService authService,
    HttpContext http,
    CancellationToken ct) =>
{
    var subjectId = http.GetSqlOSValidatedToken()?.UserId;
    if (string.IsNullOrWhiteSpace(subjectId))
        return Results.Unauthorized();
 
    var workspace = await db.Workspaces.FindAsync([id], ct);
    if (workspace == null) return Results.NotFound();
 
    var access = await authService.CheckAccessAsync(
        subjectId,
        "WORKSPACE_MANAGE",
        workspace.ResourceId);
    if (!access.Allowed)
        return Results.Json(new { error = "Permission denied" }, statusCode: 403);
 
    workspace.Name = request.Name.Trim();
    await db.SaveChangesAsync(ct);
 
    return Results.Ok(workspace);
});

Because ResourceName => Name, the backing FGA resource display name updates with the entity.

Delete pattern#

CSHARP

api.MapDelete("/workspaces/{id}", async (
    Guid id,
    AppDbContext db,
    ISqlOSFgaAuthService authService,
    HttpContext http,
    CancellationToken ct) =>
{
    var subjectId = http.GetSqlOSValidatedToken()?.UserId;
    if (string.IsNullOrWhiteSpace(subjectId))
        return Results.Unauthorized();
 
    var workspace = await db.Workspaces.FindAsync([id], ct);
    if (workspace == null) return Results.NotFound();
 
    var access = await authService.CheckAccessAsync(
        subjectId,
        "WORKSPACE_MANAGE",
        workspace.ResourceId);
    if (!access.Allowed)
        return Results.Json(new { error = "Permission denied" }, statusCode: 403);
 
    db.Workspaces.Remove(workspace);
    await db.SaveChangesAsync(ct);
 
    return Results.NoContent();
});

Deletes remove the backing resource and direct grants. If child resources still reference the resource, SqlOS throws a clear exception so the application can delete or reparent children first.