Skip to main content

Scoped Administration Model

Summary​

Keymate delegates administrative authority by binding admin capabilities to specific positions within the organizational hierarchy. Rather than granting system-wide administrative access, the platform assigns administrative roles at the Tenant, Organization, or department level. An administrator's visibility and management authority extend only within their assigned boundary — they see and manage users, roles, attributes, and department structures within their scope, with no access to entities outside it.

Why It Exists​

Centralized administration does not scale for large organizations with many departments and regulatory boundaries. A tax division administrator should manage tax division users and roles without seeing or affecting the compliance division. Scoped administration solves this by partitioning management authority along the same organizational hierarchy that governs user access. Each administrative boundary mirrors a real organizational unit, keeping authority aligned with responsibility.

Where It Fits in Keymate​

The organization model defines the hierarchical structure of Tenants and departments. The identity model defines user representations. Org-unit-aware identity links users to positions within the hierarchy. The scoped administration model builds on all three by defining which portions of the hierarchy an administrator can manage. Administrative actions produce token claims that carry the administrator's organizational scope, and the authorization layer enforces these boundaries on every management operation.

Boundaries​

This page covers how administrative authority delegates across the organizational hierarchy. It does not cover:

How It Works​

Administrative Role Scopes​

The platform distinguishes administrative roles by their scope of authority:

  • Organization-level roles grant management authority across the entire Organization and all its departments. An administrator with an Organization-level role can manage users, departments, roles, and attributes throughout the hierarchy.
  • Department-level roles grant management authority within a specific department and its sub-departments. The administrator's visibility ends at the department boundary — sibling and parent departments remain invisible.
  • Delegation roles enable an administrator to act on behalf of another user within their administrative boundary. These roles carry specific constraints that limit what the delegated session can access.

Visibility Boundaries​

An administrator's query results reflect their scope. When a department administrator lists users, the platform returns only users who hold assignments within that department or its descendants. The same filtering applies to role listings, attribute definitions, group mappings, and department structures. The administrator cannot discover entities that exist outside their boundary.

This visibility filtering operates at the data access layer. The platform reads the administrator's active organizational context from their session and applies the scope as a mandatory filter on all management queries. The administrator does not need to specify the scope — the platform enforces it automatically based on the active assignment.

Delegation Within the Hierarchy​

Administrators with delegation authority can grant administrative roles to other users within their own boundary. A department administrator can designate sub-department administrators, but cannot create administrators at the same level or above. This downward-only delegation prevents privilege escalation — an administrator cannot extend authority beyond what they hold.

When delegating, the platform validates that:

  1. The target user holds an assignment within the delegating administrator's scope
  2. The delegated role does not exceed the delegating administrator's own role set
  3. The target department falls within the delegating administrator's boundary

Session-Bound Administrative Context​

Administrative operations execute within a session that carries the administrator's organizational context. The platform binds the session to a specific organizational assignment through an organization ticket — the same mechanism that governs user context switching. This ensures that every administrative action carries an auditable scope reference.

When an administrator switches between organizational contexts via token exchange, the platform revokes the previous token and issues a new one reflecting the new administrative scope. The administrator's visibility and authority change immediately to match the new context.

Application and Resource Scoping​

Scoped administration extends to application management. An Organization-level administrator controls which applications are available within the Organization. A department-level administrator can assign available application roles to users within their department but cannot add or remove applications from the Organization's catalog. This separation ensures that application availability is an Organization-level decision while role assignment remains a departmental task.

Diagram​

Example Scenario​

Scenario​

A regional directorate has two divisions: Tax and Compliance. The Tax Division administrator needs to create a sub-department administrator for the Audit Branch. The administrator also attempts to view users in the Compliance Division.

Input​

  • Actor: Tax Division administrator
  • Resource: User management and department structure
  • Action: (1) Create an Audit Branch administrator, (2) List Compliance Division users
  • Context: The administrator holds a department-level administrative role scoped to the Tax Division

Expected Outcome​

  • Action 1 — Applied: The platform creates the Audit Branch administrator because the Audit Branch falls within the Tax Division hierarchy, and the delegated role does not exceed the Tax Division administrator's authority
  • Action 2 — Denied: The platform returns an empty result for Compliance Division users because the Compliance Division falls outside the Tax Division administrator's scope. The administrator receives no indication that users exist in that division
  • Why: Scoped administration filters all queries and mutations through the administrator's active organizational boundary. Downward delegation succeeds; cross-boundary access is silently excluded

Common Misunderstandings​

  • "Department administrators can see all users in the Organization" — No. A department administrator sees only users with assignments in their department or its sub-departments. Users assigned to sibling or parent departments are invisible.

  • "An administrator can delegate roles higher than their own" — No. The platform validates that delegated roles do not exceed the delegating administrator's role set. Upward privilege escalation is blocked.

  • "Switching organizational context retains the previous scope" — No. Context switching via token exchange revokes the previous token and issues a new one. The administrator's visibility and authority reflect the new context immediately.

warning

When an administrator is removed from a department, the administrative roles delegated by that administrator remain in place. Review delegated roles when restructuring administrative assignments to prevent orphaned authority.

Design Notes / Best Practices​

  • Assign Organization-level administrative roles sparingly. Use department-level roles for day-to-day management and reserve Organization-level access for structural changes like creating or removing departments.
  • Align administrative scopes with real reporting structures. When the organizational hierarchy mirrors the actual chain of responsibility, administrative delegation follows naturally.
  • Audit delegated administrative roles periodically. Because delegated roles persist independently of the delegating administrator, role reviews prevent authority from accumulating beyond intent.
tip

When onboarding a new department, create the administrative role assignment alongside the department structure. This ensures the department has a designated administrator from the start and avoids a gap where no one manages the new unit.

  • Delegating user management to department heads within a government agency
  • Restricting application role assignment to department-level administrators
  • Preventing cross-division visibility in regulated industries
  • Enabling temporary administrative delegation for coverage during absences

Org-Unit-Aware Identity

Department hierarchy that defines administrative boundaries

Users, Groups, Roles & Organizations

How roles resolve across organizational levels

Tenant-Scoped Identity

Tenant isolation that constrains all administrative scopes

Organization Model

Hierarchical structure that scoped administration operates within