IBeam.AccessControl.Api 2.8.0

IBeam.AccessControl.Api

IBeam.AccessControl.Api provides optional ASP.NET Core endpoint wiring for managing IBeam access-control grants, permission-role maps, and service-operation permission rules over HTTP. It is for teams that want runtime administration APIs instead of configuration-only or script-only management.

When To Use This

• You want admins or internal tools to manage resource grants dynamically.
• You want API endpoints for permission-to-role mappings.
• You want API endpoints for service-operation allow/deny rules.
• You are comfortable exposing these capabilities behind a strong authorization policy.

Do not install this package if access-control rules should only be changed through configuration, migrations, or locked-down scripts.

What This Package Contains

Architecture Fit

API <-- DTO/model object --> Service <-- Entity --> Repository

This package is API-only. Endpoints should stay thin: bind route/body data, call one access-control service method, and return the result. Authorization rules, permission evaluation, validation, and persistence belong in IBeam.AccessControl.Services and repository packages.

Quick Start

using IBeam.AccessControl.Api;
using IBeam.AccessControl.Services;

builder.Services.AddAuthentication();
builder.Services.AddAuthorization();
builder.Services.AddIBeamAccessControlServices(builder.Configuration);
builder.Services.AddIBeamServiceOperationPermissionManagement();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapIBeamAccessControl("/api", authorizationPolicy: "AccessControlAdmin");

Endpoint Overview

Default route prefix:

app.MapIBeamAccessControl("/api", authorizationPolicy: "AccessControlAdmin");

Representative endpoints:

GET    /api/tenants/{tenantId}/access-control/grants
POST   /api/tenants/{tenantId}/access-control/grants
PUT    /api/tenants/{tenantId}/access-control/grants/{grantId}
DELETE /api/tenants/{tenantId}/access-control/grants/{grantId}
POST   /api/tenants/{tenantId}/access-control/grants/check

GET    /api/tenants/{tenantId}/access-control/permission-maps
PUT    /api/tenants/{tenantId}/access-control/permission-maps/by-name/{permissionName}
PUT    /api/tenants/{tenantId}/access-control/permission-maps/by-id/{permissionId}
DELETE /api/tenants/{tenantId}/access-control/permission-maps/by-name/{permissionName}
DELETE /api/tenants/{tenantId}/access-control/permission-maps/by-id/{permissionId}

GET    /api/tenants/{tenantId}/access-control/service-permissions
POST   /api/tenants/{tenantId}/access-control/service-permissions
PUT    /api/tenants/{tenantId}/access-control/service-permissions/{ruleId}
POST   /api/tenants/{tenantId}/access-control/service-permissions/{ruleId}/disable
DELETE /api/tenants/{tenantId}/access-control/service-permissions/{ruleId}
POST   /api/tenants/{tenantId}/access-control/service-permissions/check

Example operation rule request:

{
  "pattern": "pricing.*",
  "effect": "allow",
  "subjectTypes": [ "user" ],
  "roleNames": [ "Accounting" ],
  "roleIds": [],
  "priority": 0
}

Configuration

This package primarily depends on service-layer configuration.

Service Operations, Auditing, And Permissions

The API package does not implement authorization rules itself. It should be protected by host ASP.NET Core authorization:

app.MapIBeamAccessControl("/api", authorizationPolicy: "AccessControlAdmin");

The services called by these endpoints are operation-tagged and audited by IBeam.AccessControl.Services when IBeam service auditing is enabled.

Data Storage

This API package does not create or own storage. It calls service/store abstractions.

For Azure Table schema, see ../IBeam.AccessControl.Repositories.AzureTable/README.md.

Extension Points

Extended Docs And Agent Guidance

• AI prompt: .agent/prompt.md
• Root implementation guide: ../.agent/implementation-guide.md
• Service operation permissions: ../docs/service-operation-permissions.md
• Roles, permissions, and grants: ../docs/roles-permissions-and-grants.md
• Consuming API migration prompt: ../IBeam.AI.Enablement/examples/consuming-api-migration-prompt.md

Agents should preserve the thin API pattern and keep permission logic in the service layer.

Troubleshooting

Version Notes

• Targets net10.0.
• Built for optional dynamic management.
• Package version is assigned by the repository release workflow.