Permissions
Patterns & Best Practices
The main concepts of the permission system. Used system wide across all services.
Permission Hierarchy
The permission system follows this hierarchy (from highest to lowest):
- Global Super Admin - Access to everything
- Service Platform Managers - Access to all resources in their service
- Organization Admins - Edit access to shared objects in their organization
- Object Owners/Editors - Edit access to specific objects
- Organization Members - View access to shared objects in their organization
- Object Viewers - View access to specific objects
Higher-level permissions automatically include lower-level permissions. For example, platform managers have both edit and view permissions.
Sharing an Object with an Organization
// Share a submission with an organization
await writeRelationship({
resource: 'eagle_object:submission_123',
relation: 'shared_with',
subject: 'eagle_organization:sales_team'
});
// Now all admins can edit and all members can viewGranting Direct Access to an Object
// Grant editor access to a specific user
await writeRelationship({
resource: 'eagle_object:audit_789',
relation: 'editor',
subject: 'user:alice'
});
// Grant viewer access to another user
await writeRelationship({
resource: 'eagle_object:audit_789',
relation: 'viewer',
subject: 'user:bob'
});Creating an Organization
// Add admin to organization
await writeRelationship({
resource: 'eagle_organization:engineering',
relation: 'admin',
subject: 'user:alice'
});
// Add members to organization
await writeRelationship({
resource: 'eagle_organization:engineering',
relation: 'member',
subject: 'user:bob'
});Assigning ALEC Roles
// Assign validator role
await writeRelationship({
resource: 'alec:service',
relation: 'validator',
subject: 'user:alice'
});
// Assign approver role
await writeRelationship({
resource: 'alec:service',
relation: 'approver',
subject: 'user:bob'
});Best Practices
Principle of Least Privilege
Always grant the minimum level of access required:
- Use viewer role when users only need to read data
- Use editor role when users need to modify specific objects
- Reserve organization admin for users who manage teams
- Limit platform manager and super admin roles to trusted administrators
Organization-Based Sharing
Prefer sharing with organizations over individual users when working with teams:
// ✅ Good: Share with organization
await writeRelationship({
resource: 'eagle_object:submission_123',
relation: 'shared_with',
subject: 'eagle_organization:sales_team'
});
// ❌ Less maintainable: Share with individual users
await writeRelationship({
resource: 'eagle_object:submission_123',
relation: 'viewer',
subject: 'user:alice'
});Feature Flag Management
Use feature flags to gradually roll out new features:
// Enable feature for beta testers
await writeRelationship({
resource: 'eagle_feature_flag:talon',
relation: 'talon_access',
subject: 'user:beta_tester_1'
});