generated: '2026-08-27'
method: searched
source: >-
  https://docs.lakekeeper.io/docs/latest/configuration/, https://docs.lakekeeper.io/docs/latest/api-overview/,
  https://docs.lakekeeper.io/docs/latest/concepts/, https://docs.lakekeeper.io/docs/latest/authentication/,
  https://docs.lakekeeper.io/docs/latest/gotchas/, openapi/lakekeeper-management-api-openapi.yml,
  openapi/lakekeeper-catalog-api-openapi.yml
summary: >-
  Lakekeeper is self-hosted, so every runtime convention below is set by the operator's configuration rather than by
  a vendor's shared tenancy. Three APIs share one auth model (OIDC/OAuth2 bearer JWT), one error envelope (the
  Iceberg REST ErrorModel wrapper), and one pagination style (pageToken/pageSize).
auth:
  style: bearer-jwt
  schemes:
  - OAuth2 client_credentials (Iceberg REST /v1/oauth/tokens, deprecated in the Iceberg spec in favour of an external IdP)
  - HTTP bearer JWT issued by an external OIDC provider
  - Kubernetes service-account tokens
  notes: >-
    LAKEKEEPER__OPENID_PROVIDER_URI points at the operator's IdP, which must expose
    /.well-known/openid-configuration with jwks_uri and issuer. Multiple OIDC providers can be configured at once
    via LAKEKEEPER__OPENID_PROVIDERS (since v0.13.0). Setting LAKEKEEPER__OPENID_AUDIENCE is recommended so tokens
    minted for other applications on the same IdP cannot be replayed against Lakekeeper. User ids take the form
    `oidc~<subject>`.
  docs: https://docs.lakekeeper.io/docs/latest/authentication/
idempotency:
  supported: true
  header: Idempotency-Key
  applies_to: mutating requests on the Iceberg REST Catalog API (/catalog/v1)
  scope: per warehouse
  default_enabled: true
  retention: PT30M
  grace_period: PT5M
  discovery: >-
    The server advertises support by returning the `idempotency-key-lifetime` field from GET /v1/config
    (operationId getConfig). A client can therefore discover both whether idempotency is on and how long a key
    lives, without out-of-band configuration.
  behaviour: >-
    On a repeated request carrying the same Idempotency-Key, Lakekeeper replays the original response instead of
    applying the change a second time — at-most-once execution.
  configuration:
    LAKEKEEPER__IDEMPOTENCY__ENABLED: 'true (default)'
    LAKEKEEPER__IDEMPOTENCY__LIFETIME: 'PT30M (default)'
    LAKEKEEPER__IDEMPOTENCY__GRACE_PERIOD: 'PT5M (default)'
    LAKEKEEPER__IDEMPOTENCY__CLEANUP_TIMEOUT: 'PT30S (default)'
  standard: Apache Iceberg REST Catalog idempotency specification
  docs: https://docs.lakekeeper.io/docs/latest/configuration/
  note: >-
    The Management API (/management/v1) does not document an Idempotency-Key header; its safety comes from
    idempotent verbs (PUT/DELETE) and explicit conflict responses. Idempotency-Key is a catalog-plane feature.
pagination:
  style: opaque-cursor
  request_params:
  - name: pageToken
    in: query
    description: Opaque continuation token returned by the previous page.
  - name: pageSize
    in: query
    description: Maximum number of items per page.
  response_fields:
  - next-page-token
  notes: >-
    Used on 9 Management API operations (list_warehouses, list_deleted_tabulars, list_roles, list_user, list_tasks,
    list_projects and friends) and on the Generic Table list surface, as well as on the Iceberg listNamespaces /
    listTables / listViews operations. The Iceberg REST spec requires a server to return ALL results when pageToken
    is unset; to get that behaviour from Lakekeeper set LAKEKEEPER__PAGINATION_SIZE_MAX to 4294967295 (u32::MAX).
  docs: https://docs.lakekeeper.io/docs/latest/configuration/
request_tracing:
  header: x-request-id
  direction: response
  notes: >-
    Returned as a response header on Management API operations. Lakekeeper emits structured JSON logs through the
    Rust `tracing` ecosystem with standard fields (timestamp, level, message, target), filterable with RUST_LOG;
    authorization events are separately tagged with event_source = "audit".
  docs: https://docs.lakekeeper.io/docs/latest/logging/
tenancy_headers:
- name: x-project-id
  in: header
  description: >-
    Selects the Project (top-level tenant boundary) a Management API call operates against. Present on 26
    Management operations. Where omitted, the server's default project is used.
versioning:
  api_versioning: path-prefixed (/catalog/v1, /management/v1, /lakekeeper/v1)
  product_versioning: SemVer-shaped release tags (v0.13.3 at time of profiling); Conventional Commits drive the changelog
  spec_version: OpenAPI 3.1.0 for all three first-party documents
  notes: >-
    The OpenAPI documents carry info.version "0.0.0" — the specs are generated by utoipa at build time and are not
    stamped with the server release. Version-accurate specs are served by the running server itself at /swagger-ui.
error_envelope:
  format: iceberg-rest-error-wrapper
  rfc9457: false
  media_type: application/json
  shape: '{"error": {"message": string, "type": string, "code": integer, "stack": [string]}}'
  schema: IcebergErrorResponse -> ErrorModel
  notes: >-
    All three APIs share the same envelope. This is NOT RFC 9457 application/problem+json — it is the Iceberg REST
    Catalog error wrapper, which predates and is incompatible with problem+json. `type` is an internal error type
    string, `code` mirrors the HTTP status.
  catalog: errors/lakekeeper-problem-types.yml
rate_limit_signaling:
  published: false
  notes: >-
    Lakekeeper publishes no rate limits and returns no X-RateLimit-*/RateLimit-* headers. It is self-hosted server
    software: capacity is the operator's, not a vendor's. The nearest published guards are
    LAKEKEEPER__MAX_REQUEST_BODY_SIZE (default 2 MB) and LAKEKEEPER__MAX_REQUEST_TIME (default 30s). Lakekeeper does
    honour 429 + Retry-After as a CLIENT when calling outbound identity providers and cloud STS/SAS endpoints.
  detail: rate-limits/lakekeeper-rate-limits.yml
dry_run_mode:
  supported: partial
  surface: cli
  detail: >-
    `lakekeeper openfga reconcile --dry-run` computes and reports the OpenFGA tuple diff without writing. No HTTP
    API operation exposes a dry-run parameter, so for an agent calling the API this is `na`.
conditional_requests:
  etag: true
  detail: >-
    The Iceberg REST Catalog loadTable operation accepts an If-None-Match request header and can answer 304, so a
    client can revalidate table metadata without refetching it.
reversibility:
  grade: verified
  applies_to: catalog-plane table and view deletion
  summary: >-
    Lakekeeper's destructive catalog operation — dropping a table or view — is reversible when the Warehouse is
    configured for soft deletion, and the recovery window is a stated, machine-readable number rather than an
    implied one.
  reversals:
  - action: drop a table or view
    forward_operation: dropTable / dropView (openapi/lakekeeper-catalog-api-openapi.yml)
    reversal_operation: undrop_tabulars
    reversal_path: POST /management/v1/warehouse/{warehouse_id}/deleted-tabulars/undrop
    discovery_operation: list_deleted_tabulars
    discovery_path: GET /management/v1/warehouse/{warehouse_id}/deleted-tabulars
    window: >-
      Operator-configured per Warehouse. TabularDeleteProfile is a oneOf: type `hard` (no window — deletion is
      immediate and irreversible) or type `soft` with a REQUIRED `expiration-seconds` integer. The expiration delay
      is fixed at the moment of dropping — changing the Warehouse setting afterwards affects only newly dropped
      tables. Read the live value with get_warehouse; change it with update_warehouse_delete_profile.
    window_source: https://docs.lakekeeper.io/docs/latest/concepts/#soft-deletion
    caveat: >-
      Recovery is only possible on Warehouses with soft deletion enabled. A Warehouse on the `hard` delete profile
      has NO reversal path. An agent must read the delete profile before treating a drop as recoverable.
  - action: deactivate a warehouse
    forward_operation: deactivate_warehouse
    reversal_operation: activate_warehouse
    reversal_path: POST /management/v1/warehouse/{warehouse_id}/activate
    window: unbounded — deactivation is a status flag, not a deletion
    window_source: https://docs.lakekeeper.io/docs/latest/api/management/
  - action: cancel an in-flight table scan plan
    forward_operation: planTableScan
    reversal_operation: cancelPlanning
    reversal_path: DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}
    window: while the plan is still active
    window_source: https://docs.lakekeeper.io/docs/latest/api/catalog/
  guards:
  - name: protection flags
    detail: >-
      set_warehouse_protection, set_namespace_protection, set_table_protection, set_view_protection and
      set_generic_table_protection mark an object protected so that a delete is refused outright — a pre-emptive
      guard that complements the post-hoc undrop path.
  - name: cascade refusal
    detail: >-
      A Warehouse or Namespace cannot be dropped through the /catalog API while child objects exist — including
      soft-deleted tables. There is deliberately no cascade-drop; the docs record it as planned for a future
      Management API release.
  irreversible:
  - operation: dropTable with purgeRequested=true on a hard-delete Warehouse
    note: Data files are removed. No reversal path.
  - operation: delete_project
    note: No undelete endpoint exists in the Management API.
  - operation: delete_warehouse
    note: >-
      No undelete endpoint. Deactivate (reversible) is the safe alternative when the intent is to take a warehouse
      out of service.
  - operation: delete_user / delete_role
    note: No undelete endpoint; recreate is the only path, and the new principal gets a new id.
cross_references:
  errors: errors/lakekeeper-problem-types.yml
  lifecycle: lifecycle/lakekeeper-lifecycle.yml
  authentication: authentication/lakekeeper-authentication.yml
  rate_limits: rate-limits/lakekeeper-rate-limits.yml
  scopes: scopes/lakekeeper-scopes.yml