Principle:Treeverse LakeFS API Authorization Specification
| Knowledge Sources | |
|---|---|
| Domains | Authorization, API Specification, RBAC |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The API Authorization Specification principle defines the role-based access control (RBAC) model and resource management patterns that govern how users, groups, credentials, and policies are administered in lakeFS.
Description
lakeFS implements a policy-based RBAC authorization model, where access control decisions are determined by policy statements attached to users and groups. This principle establishes the following key design patterns:
Resource Hierarchy:
- Users are the primary identity entities, each identified by a unique username
- Groups aggregate users into logical collections (e.g., Admins, SuperUsers, Developers, Viewers)
- Policies define permission rules through statements with allow/deny effects
- Credentials (access key pairs) provide programmatic access tokens tied to specific users
Policy Statement Model: Each policy contains one or more statements that specify:
- An effect (allow or deny) determining whether the action is permitted
- A resource identifying the target (using ARN-style resource identifiers)
- A list of actions that the statement applies to
- Optional conditions (such as IpAddress restrictions) for fine-grained control
Many-to-Many Relationships: Policies can be attached to both users and groups, and users can belong to multiple groups. The effective policies for a user are the union of directly attached policies and all policies inherited through group membership. This enables flexible, composable permission models.
Credential Lifecycle Management: The specification defines a complete lifecycle for access key credentials, including creation (with optional explicit key specification), listing, retrieval, and deletion. Credentials are always associated with a specific user.
External Principal Support (Experimental): The specification includes experimental endpoints for managing external principals, enabling integration with external identity systems such as AWS IAM roles.
Usage
Apply this principle when implementing authorization logic, creating access control policies, or integrating external identity providers with lakeFS. New authorization features should follow the RBAC model defined in this specification, attaching permissions via policy statements rather than hardcoding access rules. Group-based permission inheritance should be preferred over direct user-policy attachment for maintainability.
Theoretical Basis
The authorization specification is built on well-established access control theory and design principles:
Role-Based Access Control (RBAC): RBAC is an industry-standard access control model (NIST RBAC standard) where permissions are assigned to roles (groups in lakeFS), and users inherit permissions through role membership. This reduces administrative overhead compared to assigning permissions to individual users.
Policy-Based Access Control (PBAC): The statement model extends basic RBAC with policy-based evaluation, where each statement explicitly defines the effect, resource, and actions. This follows the same pattern used by AWS IAM policies, making the model familiar to cloud-native practitioners.
Principle of Least Privilege: The allow/deny model with explicit resource scoping enables administrators to grant only the minimum necessary permissions. Deny statements take precedence, allowing broad permissions to be narrowed for specific resources.
Separation of Concerns: Authorization is defined independently from authentication. The authorization API uses only JWT token authentication, creating a clean boundary between identity verification and permission evaluation.
Composability: The many-to-many relationship between policies, users, and groups enables composable security configurations. Standard policies (FSFullAccess, FSReadWriteAll, FSReadAll) can be combined and attached at different levels to create nuanced access control models.
Pagination and Scalability: All list endpoints follow a consistent pagination pattern with prefix, after, and amount parameters, ensuring the authorization API can scale to large numbers of users, groups, and policies without performance degradation.