> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modeling Permissions

How to model permissions in Lumos

## Overview

Modeling permissions in Lumos follows a consistent approach:

1. **Identify Resource Hierarchies**

   * If your application has a concept of “resource groups,” “organizations,” or “projects,” these become **Resources** in Lumos.
   * Each resource has a unique identifier and a human-readable label.
2. **Define Permissions**

   * Each type of permission or role is an **Permission**. For example, “Viewer,” “Editor,” “Billing Admin,” etc.
   * If your application requires scoping permissions to a resource (e.g., a project in your system), you represent that in the resource\_id field when returning data from list\_entitlements.
3. **Handle Global vs. Scoped Permissions**

   * **Global**: The permission is the same system-wide (no resource context). Return an empty resource\_id (or some global identifier) in list\_entitlements.
   * **Scoped**: The permission only applies to a particular resource context (e.g., role in a certain Slack workspace). Return the relevant resource identifier in the list\_entitlements response so Lumos knows to associate it with that resource.
4. **Assign/Unassign Permissions**

   * Lumos uses assign\_entitlement and unassign\_entitlement to grant or revoke permissions from a user account in your application.
   * If your system requires additional constraints (like minimum or maximum assignments, or license seat counts), incorporate that logic in your connector’s implementation.
5. **Account and Permission Lifecycle**

   * Typically, an account is created or updated (create\_account, update\_account) with some baseline permissions that are deemed mandatory from an organizational policy.
   * Additional permissions are granted later via assign\_entitlement.
   * Permissions are removed via unassign\_entitlement, and the account is eventually deactivated (deactivate\_account) or deleted (delete\_account) as the identity leaves the organization or changes roles.

<br />

## Best Practices for Architects

1. **Keep Permissions Granular**

   * Define each permission, license, or group at the appropriate level of granularity so that Lumos can manage them individually. Overly broad permissions can limit the benefits of fine-grained governance.
2. **Use Resource Context Where Applicable**

   * If your application’s permissions are resource-scoped, implement list\_resources thoroughly. This allows Lumos to accurately represent which permissions belong to which resource.
3. **Handle Lifecycle Events Carefully**

   * Decide what “deactivate” vs. “delete” should do in your system. Some organizations prefer to “soft delete” (disable) accounts for compliance reasons. Others allow full deletion.
   * If your system cannot truly delete an account (for data retention reasons), ensure your connector’s delete\_account operation is clearly documented.
4. **Leverage Custom Attributes**

   * If your application requires special attributes (e.g., a “cost center” or “department code”), add them to list\_custom\_attributes\_schema so that Lumos can track and manage them as part of the user identity.
5. **Follow a Consistent Naming Convention**

   * For permissions and resources, use clear, descriptive names that help administrators understand what the permission or container is for.
6. **Performance Considerations**

   * If your application has thousands or millions of users or permissions, ensure your connector endpoints (like list\_accounts, list\_entitlements) implement pagination or incremental synchronization if supported. This keeps synchronization timely and efficient.
7. **Security and Credential Management**

   * Encourage the use of secure authentication methods (OAuth 2.0 over user/password or API keys) when possible.
   * Regularly refresh tokens (refresh\_access\_token) and validate credentials (validate\_credentials).

## Conclusion

By understanding the Lumos object model—identities, accounts, resources, permissions—and how data flows between Lumos and the connected systems, architects and developers can design robust, scalable integrations. Lumos’s read and write capabilities allow for comprehensive synchronization and governance of user accounts and their permissions across a wide variety of applications.

When modeling permissions, always map the application’s permissions structure (roles, groups, licenses) as accurately as possible, utilizing resource scoping where needed. This ensures that Lumos administrators can rely on correct data to automate and govern access across the organization.