Implementation:Treeverse LakeFS Authorization API Spec

Knowledge Sources	Treeverse_LakeFS
Domains	Authorization, API Specification, RBAC
Last Updated	2026-02-08 00:00 GMT

Overview

This OpenAPI 3.0 specification defines the lakeFS authorization API, providing a comprehensive set of endpoints for managing users, groups, credentials, policies, and external principals under a role-based access control (RBAC) model.

Description

The authorization.yml file is an OpenAPI 3.0 specification (version 0.1.0) that describes the lakeFS authorization API used to manage users, groups, credentials, and policies. The API is served at the /api/v1 base path and is secured exclusively via jwt_token (HTTP Bearer with JWT format).

The specification defines CRUD operations across five major resource categories:

User Management:

• GET /auth/users (listUsers) -- List all users with pagination, filtering by prefix, email, or external_id
• POST /auth/users (createUser) -- Create a new user, also used during setup to create the initial admin user
• GET /auth/users/{userId} (getUser) -- Retrieve a specific user by ID
• DELETE /auth/users/{userId} (deleteUser) -- Delete a user
• PUT /auth/users/{userId}/password (updatePassword) -- Update a user's password
• PUT /auth/users/{userId}/friendly_name (updateUserFriendlyName) -- Update a user's display name

Group Management:

• GET /auth/groups (listGroups) -- List all groups with pagination
• POST /auth/groups (createGroup) -- Create a new group (default groups: Admins, SuperUsers, Developers, Viewers)
• GET /auth/groups/{groupId} (getGroup) -- Retrieve a specific group
• DELETE /auth/groups/{groupId} (deleteGroup) -- Delete a group

Policy Management:

• GET /auth/policies (listPolicies) -- List all policies with pagination
• POST /auth/policies (createPolicy) -- Create a new policy (default policies: FSFullAccess, FSReadWriteAll, FSReadAll, etc.)
• GET /auth/policies/{policyId} (getPolicy) -- Retrieve a specific policy
• PUT /auth/policies/{policyId} (updatePolicy) -- Update an existing policy
• DELETE /auth/policies/{policyId} (deletePolicy) -- Delete a policy

Membership and Policy Attachment:

• GET /auth/groups/{groupId}/members (listGroupMembers) -- List users in a group
• PUT /auth/groups/{groupId}/members/{userId} (addGroupMembership) -- Add a user to a group
• DELETE /auth/groups/{groupId}/members/{userId} (deleteGroupMembership) -- Remove a user from a group
• GET /auth/users/{userId}/groups (listUserGroups) -- List groups a user belongs to
• GET /auth/users/{userId}/policies (listUserPolicies) -- List policies for a user (supports effective flag for inherited policies)
• PUT /auth/users/{userId}/policies/{policyId} (attachPolicyToUser) -- Attach a policy to a user
• DELETE /auth/users/{userId}/policies/{policyId} (detachPolicyFromUser) -- Detach a policy from a user
• GET /auth/groups/{groupId}/policies (listGroupPolicies) -- List policies attached to a group
• PUT /auth/groups/{groupId}/policies/{policyId} (attachPolicyToGroup) -- Attach a policy to a group
• DELETE /auth/groups/{groupId}/policies/{policyId} (detachPolicyFromGroup) -- Detach a policy from a group

Credential Management:

• GET /auth/users/{userId}/credentials (listUserCredentials) -- List credentials for a user
• POST /auth/users/{userId}/credentials (createCredentials) -- Create credentials, optionally with specified access/secret keys
• GET /auth/users/{userId}/credentials/{accessKeyId} (getCredentialsForUser) -- Get specific credentials for a user
• DELETE /auth/users/{userId}/credentials/{accessKeyId} (deleteCredentials) -- Delete credentials
• GET /auth/credentials/{accessKeyId} (getCredentials) -- Get credentials by access key ID

External Principals (Experimental):

• GET /auth/users/{userId}/external/principals/ls (listUserExternalPrincipals) -- List external principals for a user
• POST /auth/users/{userId}/external/principals (createUserExternalPrincipal) -- Create an external principal for a user
• DELETE /auth/users/{userId}/external/principals (deleteUserExternalPrincipal) -- Delete an external principal
• GET /auth/external/principals (getExternalPrincipal) -- Get an external principal by ID

Other:

• GET /healthcheck (healthCheck) -- Check API server availability
• GET /config/version (getVersion) -- Get server version
• POST /auth/tokenid/claim (claimTokenId) -- Claim a token ID (internal use)

The Policy model uses an RBAC Statement structure with effect (allow/deny), resource, action (list of strings), and optional condition support with operators like IpAddress.

Usage

Use this specification when implementing or integrating with the lakeFS authorization layer. It is the contract for building an RBAC authentication server, generating client SDKs, or implementing custom authorization services that manage lakeFS users, groups, credentials, and access policies.

Code Reference

Source Location

• Repository: Treeverse_LakeFS
• File: api/authorization.yml

Signature

openapi: "3.0.0"
info:
  title: lakeFS authorization API
  description: authorization API used to manages users, groups, credentials and policies
  version: 0.1.0
servers:
  - url: "/api/v1"
security:
  - jwt_token: []

Import

# Reference this spec via OpenAPI tooling:
$ref: "api/authorization.yml"

I/O Contract

Inputs

Name	Type	Required	Description
UserCreation.username	string	Yes	Unique identifier for the user (email for password-based auth)
UserCreation.invite	boolean	No	If true, send invitation email along with user creation
UserCreation.source	string	No	User source, based on implementation
UserCreation.external_id	string	No	External system identifier for the user
GroupCreation.id	string	Yes	Unique human-readable identifier for the group
GroupCreation.description	string	No	Description of the group
Policy.name	string	Yes	Unique human-readable name for the policy
Policy.statement	array of Statement	Yes	List of RBAC policy statements (min 1)
Statement.effect	string (enum: allow, deny)	Yes	Whether the statement allows or denies access
Statement.resource	string	Yes	Resource ARN the statement applies to
Statement.action	array of strings	Yes	Actions permitted or denied (min 1)
Statement.condition	object	No	Optional conditions for when the statement applies
PaginationPrefix	string (query)	No	Filter results by prefix
PaginationAfter	string (query)	No	Pagination cursor for subsequent pages
PaginationAmount	integer (query)	No	Number of items per page (default: 100, max: 1000)
effective	boolean (query)	No	For listUserPolicies: include inherited policies from groups

Outputs

Name	Type	Description
User	object	Contains username, creation_date, friendly_name, email, source, external_id
UserList	object	Pagination component plus array of User objects
Group	object	Contains id, name, description, creation_date
GroupList	object	Pagination component plus array of Group objects
Policy	object	Contains name, creation_date, statement array, optional acl
PolicyList	object	Pagination component plus array of Policy objects
Credentials	object	Contains access_key_id and creation_date
CredentialsList	object	Pagination component plus array of Credentials objects
CredentialsWithSecret	object	Contains access_key_id, secret_access_key, creation_date, user_name
ExternalPrincipal	object	Contains user_id and id
VersionConfig.version	string	Server version string
Error.message	string	Short message explaining the error

Usage Examples

Example

# Create a user
POST /api/v1/auth/users
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "username": "developer@example.com",
  "invite": true
}

# Response (201 Created)
{
  "username": "developer@example.com",
  "creation_date": 1707350400,
  "friendly_name": "",
  "email": "developer@example.com"
}

# Create a policy with RBAC statement
POST /api/v1/auth/policies
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "ReadOnlyPolicy",
  "statement": [
    {
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/my-repo/*",
      "action": ["fs:ReadObject", "fs:ListObjects"]
    }
  ]
}

# Response (201 Created)
{
  "name": "ReadOnlyPolicy",
  "creation_date": 1707350400,
  "statement": [
    {
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/my-repo/*",
      "action": ["fs:ReadObject", "fs:ListObjects"]
    }
  ]
}

# Attach policy to a group
PUT /api/v1/auth/groups/Developers/policies/ReadOnlyPolicy
Authorization: Bearer <jwt_token>

# Response (201 Created)

Related Pages

• Principle:Treeverse_LakeFS_API_Authorization_Specification