Lakekeeper Authorization API

openapi: 3.2.0
info:
  title: Lakekeeper＋ Management Authorization API
  description: Lakekeeper is a rust-native Apache Iceberg REST Catalog implementation. The Management API provides endpoints to manage the server, projects, warehouses, users, and roles. If Authorization is enabled, permissions can also be managed. An interactive Swagger-UI for the specific Lakekeeper Version and configuration running is available at `/swagger-ui/#/` of Lakekeeper (by default http://localhost:8181/swagger-ui/#/).
  license:
    name: Vakamo Enterprise License
  version: 0.0.0
servers:
- url: '{scheme}://{host}{basePath}'
  description: Lakekeeper Management API
  variables:
    basePath:
      default: ''
      description: Optional path prefix (starting with '/') to be prepended to all routes
    host:
      default: localhost
      description: The host (and optional port) for the specified server
    scheme:
      default: https
      description: The scheme of the URI, either http or https
security:
- bearerAuth: []
tags:
- name: Authorization
paths:
  /management/v1/action/batch-check:
    post:
      tags:
      - Authorization
      summary: Batch Check Catalog Actions
      description: 'Performs authorization checks for multiple catalog actions in a single request.

        This endpoint allows checking permissions across different resource types (servers, projects,

        warehouses, namespaces, tables, and views) efficiently.


        The endpoint supports:

        - Checking actions for different identities (users or roles)

        - Mixing different resource types in a single batch

        - Optional error-on-not-found behavior (default: treat missing resources as denied)


        Each check in the request can optionally override the identity being checked.

        If no identity is specified, the current user''s identity is used.'
      operationId: batch_check_actions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CatalogActionsBatchCheckRequest'
        required: true
      responses:
        '200':
          description: Batch check results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogActionsBatchCheckResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
components:
  schemas:
    TabularIdentOrUuid:
      oneOf:
      - type: object
        required:
        - warehouse-id
        - table-id
        properties:
          table-id:
            type: string
            format: uuid
          warehouse-id:
            type: string
            format: uuid
      - type: object
        required:
        - namespace
        - table
        - warehouse-id
        properties:
          namespace:
            type: array
            items:
              type: string
          table:
            type: string
            description: Name of the table, view, or generic table.
          warehouse-id:
            type: string
            format: uuid
      description: 'Identifier for a tabular (table, view, or generic table) — either a UUID

        or its name and namespace. Wire format primary names are `table-id` and

        `table`; `view_id` / `view` and `generic_table_id` / `generic_table` are

        accepted as input aliases for client ergonomics.'
    LakekeeperProjectAction:
      oneOf:
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_warehouse
          name:
            type:
            - string
            - 'null'
            description: Name of the warehouse to create.
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - delete
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - rename
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_metadata
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_warehouses
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - include_in_list
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_role
          name:
            type:
            - string
            - 'null'
            description: Name of the role to create.
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_roles
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - search_roles
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_endpoint_statistics
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - modify_task_queue_config
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_task_queue_config
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_project_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - control_project_tasks
    LakekeeperNamespaceAction:
      oneOf:
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_table
          name:
            type:
            - string
            - 'null'
            description: Name of the table to create.
          properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
          table_id:
            type:
            - string
            - 'null'
            format: uuid
            description: Table ID, if externally provided (e.g. via register).
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_view
          name:
            type:
            - string
            - 'null'
            description: Name of the view to create.
          properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_namespace
          name:
            type:
            - string
            - 'null'
            description: Name of the namespace to create.
          properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - delete
          force:
            type: boolean
            description: 'Whether the warehouse-configured soft-deletion is bypassed, i.e.

              contained tabulars are hard-deleted immediately instead of being

              recoverable for the configured grace period.'
          purge:
            type: boolean
            description: Whether the underlying data/metadata files are physically purged.
          recursive:
            type: boolean
            description: 'Whether the drop recurses into child namespaces, tables and views,

              deleting the entire subtree rooted at this namespace.'
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - update_properties
          removed_properties:
            type: array
            items:
              type: string
          updated_properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_metadata
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_tables
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_views
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_namespaces
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_everything
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - set_protection
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - include_in_list
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_generic_table
          base_location:
            type:
            - string
            - 'null'
            description: 'User-supplied base location override — primary lever for

              path-based authorization policy.'
          format:
            type:
            - string
            - 'null'
            description: 'Generic table format (e.g. "lance", "delta") — primary lever for

              format-based authorization policy.'
          generic_table_id:
            type:
            - string
            - 'null'
            format: uuid
            description: Generic table ID, if externally provided.
          name:
            type:
            - string
            - 'null'
            description: Name of the generic table to create.
          properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_generic_tables
    CatalogActionCheckItem:
      type: object
      description: A single check item with optional identity override
      required:
      - operation
      properties:
        id:
          type:
          - string
          - 'null'
          description: 'Optional identifier for this check (returned in response).

            If not specified, the index in the request array will be used.'
        identity:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/UserOrRole'
            description: 'The user or role to check access for.

              If not specified, the identity of the user making the request is used.'
        operation:
          $ref: '#/components/schemas/CatalogActionCheckOperation'
          description: The operation to check
    ErrorModel:
      type: object
      description: JSON error payload returned in a response with further details on the error
      required:
      - message
      - type
      - code
      properties:
        code:
          type: integer
          format: int32
          description: HTTP response code
          minimum: 0
        message:
          type: string
          description: Human-readable error message
        stack:
          type: array
          items:
            type: string
        type:
          type: string
          description: Internal type definition of the error
    IcebergErrorResponse:
      type: object
      description: JSON wrapper for all error responses (non-2xx)
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorModel'
    LakekeeperViewAction:
      oneOf:
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - drop
          force:
            type: boolean
            description: 'Whether the warehouse-configured soft-deletion is bypassed, i.e. the

              view is hard-deleted immediately instead of being recoverable for the

              configured grace period. Extra destructive — irreversible right away.'
          purge:
            type: boolean
            description: Whether the underlying metadata files are physically purged from storage.
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_metadata
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - select
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - commit
          removed_properties:
            type: array
            items:
              type: string
          updated_properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - include_in_list
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - rename
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - undrop
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - control_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - set_protection
    UserOrRole:
      oneOf:
      - type: object
        title: UserOrRoleUser
        description: Id of the user
        required:
        - user
        properties:
          user:
            type: string
            description: Id of the user
      - type: object
        title: UserOrRoleRole
        description: Id of the role
        required:
        - role
        properties:
          role:
            type: string
            format: uuid
            description: Id of the role
      description: Identifies a user or a role
    NamespaceIdentOrUuid:
      oneOf:
      - type: object
        required:
        - namespace-id
        - warehouse-id
        properties:
          namespace-id:
            type: string
            format: uuid
          warehouse-id:
            type: string
            format: uuid
      - type: object
        required:
        - namespace
        - warehouse-id
        properties:
          namespace:
            type: array
            items:
              type: string
          warehouse-id:
            type: string
            format: uuid
      description: Identifier for a namespace, either a UUID or its name and warehouse ID
    LakekeeperWarehouseAction:
      oneOf:
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_namespace
          name:
            type:
            - string
            - 'null'
            description: Name of the namespace to create.
          properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - delete
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - update_storage
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - update_storage_credential
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_metadata
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_config
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_namespaces
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_everything
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - use
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - include_in_list
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - deactivate
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - activate
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - rename
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_deleted_tabulars
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - modify_soft_deletion
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_task_queue_config
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - modify_task_queue_config
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_all_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - control_all_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - set_protection
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - set_format_version_policy
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_endpoint_statistics
    LakekeeperServerAction:
      oneOf:
      - type: object
        description: Can create items inside the server (can create Warehouses).
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - create_project
          name:
            type:
            - string
            - 'null'
            description: Name of the project to create.
          project_id:
            type:
            - string
            - 'null'
            description: Project ID, if externally provided.
      - type: object
        description: Can update all users on this server.
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - update_users
      - type: object
        description: Can delete all users on this server.
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - delete_users
      - type: object
        description: Can List all users on this server.
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - list_users
      - type: object
        description: Can provision user
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - provision_users
    LakekeeperTableAction:
      oneOf:
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - drop
          force:
            type: boolean
            description: 'Whether the warehouse-configured soft-deletion is bypassed, i.e. the

              table is hard-deleted immediately instead of being recoverable for the

              configured grace period. Extra destructive — irreversible right away.'
          purge:
            type: boolean
            description: Whether the underlying data files are physically purged from storage.
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - write_data
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - read_data
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_metadata
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - commit
          removed_properties:
            type: array
            items:
              type: string
          updated_properties:
            type: object
            additionalProperties:
              type: string
            propertyNames:
              type: string
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - rename
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - include_in_list
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - undrop
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - control_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - set_protection
    CatalogActionsBatchCheckResult:
      type: object
      required:
      - allowed
      properties:
        allowed:
          type: boolean
        id:
          type:
          - string
          - 'null'
    LakekeeperGenericTableAction:
      oneOf:
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - drop
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - read_data
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - write_data
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_metadata
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - rename
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - include_in_list
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - undrop
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - get_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - control_tasks
      - type: object
        required:
        - action
        properties:
          action:
            type: string
            enum:
            - set_protection
    CatalogActionsBatchCheckResponse:
      type: object
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CatalogActionsBatchCheckResult'
    CatalogActionsBatchCheckRequest:
      type: object
      required:
      - checks
      properties:
        checks:
          type: array
          items:
            $ref: '#/components/schemas/CatalogActionCheckItem'
          description: List of checks to perform
        error-on-not-found:
          type: boolean
          description: 'If true, return 404 error when resources are not found.

            If false, treat missing resources as denied (allowed = false).

            Defaults to false.'
    CatalogActionCheckOperation:
      oneOf:
      - type: object
        required:
        - server
        properties:
          server:
            type: object
            required:
            - action
            properties:
              action:
                $ref: '#/components/schemas/LakekeeperServerAction'
      - type: object
        required:
        - project
        properties:
          project:
            type: object
            required:
            - action
            properties:
              action:
                $ref: '#/components/schemas/LakekeeperProjectAction'
              project-id:
                type:
                - string
                - 'null'
                format: uuid
      - type: object
        required:
        - warehouse
        properties:
          warehouse:
            type: object
            required:
            - action
            - warehouse-id
            properties:
              action:
                $ref: '#/components/schemas/LakekeeperWarehouseAction'
              warehouse-id:
                type: string
                format: uuid
      - type: object
        required:
        - namespace
        properties:
          namespace:
            allOf:
            - $ref: '#/components/schemas/NamespaceIdentOrUuid'
            - type: object
              required:
              - action
              properties:
                action:
                  $ref: '#/components/schemas/LakekeeperNamespaceAction'
      - type: object
        required:
        - table
        properties:
          table:
            allOf:
            - $ref: '#/components/schemas/TabularIdentOrUuid'
            - type: object
              required:
              - action
              properties:
                action:
                  $ref: '#/components/schemas/LakekeeperTableAction'
      - type: object
        required:
        - view
        properties:
          view:
            allOf:
            - $ref: '#/components/schemas/TabularIdentOrUuid'
            - type: object
              required:
              - action
              properties:
                action:
                  $ref: '#/components/schemas/LakekeeperViewAction'
      - type: object
        required:
        - generic-table
        properties:
          generic-table:
            allOf:
            - $ref: '#/components/schemas/TabularIdentOrUuid'
            - type: object
              required:
              - action
              properties:
                action:
                  $ref: '#/components/schemas/LakekeeperGenericTableAction'
      description: Represents an action on an object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT