Implementation:Treeverse LakeFS Authentication API Spec

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

Overview

This OpenAPI 3.0 specification defines the lakeFS authentication HTTP API, providing endpoints for user login via LDAP, STS, OIDC, and external principals along with multiple security scheme definitions.

Description

The authentication.yml file is an OpenAPI 3.0 specification (version 0.1.0) licensed under Apache 2.0 that describes the lakeFS authentication HTTP API. It serves as the contract for all authentication-related interactions with the lakeFS server at the /api/v1 base path.

The specification defines five security schemes:

• basic_auth -- Standard HTTP Basic authentication
• jwt_token -- HTTP Bearer authentication using JWT tokens
• cookie_auth -- API key-based authentication via the internal_auth_session cookie
• oidc_auth -- API key-based authentication via the oidc_auth_session cookie for OpenID Connect
• saml_auth -- API key-based authentication via the saml_auth_session cookie for SAML

The API exposes five operational endpoints:

• POST /ldap/login -- Authenticate a user via LDAP using username and password, returning an LdapAuthResponse with the external user identifier (DN)
• POST /auth/external/principal/login -- Authenticate using an external authenticator, returning an ExternalPrincipal
• POST /sts/login -- Authenticate via STS using an authorization code, state, and redirect URI, returning OIDC token claims
• GET /oidc/callback -- Handle the OIDC OAuth callback, returning a 302 redirect on success
• GET /healthcheck -- Verify the API server is running (returns 204 No Content)

The specification also defines reusable schemas for pagination, error handling, user management, access key credentials, authentication tokens, stats events, and LDAP/STS/OIDC data structures.

Usage

Use this specification when implementing or consuming the lakeFS authentication API. It provides the contract for client code generation, server stub generation, and API documentation for all authentication flows supported by lakeFS, including LDAP, OIDC, SAML, STS, and external principal authentication.

Code Reference

Source Location

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

Signature

openapi: "3.0.0"
info:
  description: lakeFS authentication HTTP API
  title: lakeFS authentication API
  license:
    name: "Apache 2.0"
  version: 0.1.0
servers:
  - url: "/api/v1"
security:
  - jwt_token: []
  - basic_auth: []
  - cookie_auth: []
  - oidc_auth: []
  - saml_auth: []

Import

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

I/O Contract

Inputs

Name	Type	Required	Description
LdapAuthRequest.username	string	Yes	LDAP username for login
LdapAuthRequest.password	string	Yes	LDAP password for login
StsAuthRequest.code	string	Yes	Authorization code for STS login
StsAuthRequest.state	string	Yes	State parameter for STS login
StsAuthRequest.redirect_uri	string	Yes	Redirect URI for STS login
IdentityRequest	object	No	Request body for external principal login
PaginationPrefix	string (query)	No	Filter items by prefix
PaginationAfter	string (query)	No	Return items after this value
PaginationAmount	integer (query)	No	Number of items to return (default: 100, max: 1000)

Outputs

Name	Type	Description
LdapAuthResponse.external_user_identifier	string	The user DN in LDAP if authentication succeeds
ExternalPrincipal.id	string	Unique identifier of the external principal
oidc_token_data.claims	object (map of strings)	Claims returned from the OIDC token provider
AuthenticationToken.token	string	JWT token for authenticated requests
AuthenticationToken.token_expiration	integer (int64)	Token expiration as Unix Epoch in seconds
Error.message	string	Short message explaining the error

Usage Examples

Example

# LDAP Login Request
POST /api/v1/ldap/login
Content-Type: application/json

{
  "username": "cn=admin,dc=example,dc=org",
  "password": "secret"
}

# Response (200 OK)
{
  "external_user_identifier": "cn=admin,dc=example,dc=org"
}

# STS Login Request
POST /api/v1/sts/login
Content-Type: application/json

{
  "code": "auth_code_from_provider",
  "state": "random_state_string",
  "redirect_uri": "https://lakefs.example.com/oidc/callback"
}

# Response (200 OK)
{
  "claims": {
    "sub": "user@example.com",
    "iss": "https://idp.example.com"
  }
}

Related Pages

• Principle:Treeverse_LakeFS_API_Authentication_Specification