openapi: 3.2.0
info:
  title: Lakekeeper＋ Management Permissions Cedar 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/#/](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: permissions-cedar
  description: Cedar Authorization Management. Only available if Cedar authorization is enabled.
paths:
  /management/v1/permissions/cedar/entity-sources:
    get:
      tags:
      - permissions-cedar
      summary: Get information about active cedar entity sources
      operationId: list_cedar_entity_sources
      responses:
        '200':
          description: Active cedar entity sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCedarEntitySourcesResponse'
  /management/v1/permissions/cedar/policy-list:
    post:
      tags:
      - permissions-cedar
      summary: Get active Cedar policies
      operationId: list_cedar_policies
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCedarPoliciesQuery'
        required: true
      responses:
        '200':
          description: Active policies that match the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCedarPoliciesResponse'
  /management/v1/permissions/cedar/policy-sources:
    get:
      tags:
      - permissions-cedar
      summary: Get information about active cedar policy sources
      operationId: list_cedar_policy_sources
      responses:
        '200':
          description: Active cedar policy sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCedarPolicySourcesResponse'
  /management/v1/permissions/cedar/resolve-entities:
    post:
      tags:
      - permissions-cedar
      summary: 'Resolve Cedar entities for a given resource, returning the full entity

        hierarchy that would be used in an authorization decision.'
      description: 'Follows the `emit_authz` pattern: event context is built upfront, and ALL

        fallible work runs inside a single async block whose `Result` is passed to

        `emit_authz`. Every failure — catalog errors, role-lookup failures,

        authorization denials — is audited.


        Authorization gate: `IntrospectAuthorization` on the target resource, checked

        via the upstream `require_*_action` / `load_and_authorize_*` helpers (parallel

        fetches, TOCTOU-safe cache refresh, canonical error handling).'
      operationId: resolve_cedar_entities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveCedarEntitiesRequest'
        required: true
      responses:
        '200':
          description: Resolved Cedar entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveCedarEntitiesResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
  /management/v1/permissions/cedar/schema:
    get:
      tags:
      - permissions-cedar
      summary: Get the currently active Cedar schema.
      operationId: get_cedar_schema
      responses:
        '200':
          description: Currently active cedar schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCedarSchemaResponse'
components:
  schemas:
    ResolveCedarEntitiesRequest:
      type: object
      description: Request body for resolving Cedar entities.
      required:
      - resource
      properties:
        principal:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/UserOrRole'
            description: 'Optional principal to resolve entities for.

              If not specified, the identity of the caller is used.'
        resource:
          $ref: '#/components/schemas/CedarResolveResource'
          description: The resource to resolve entities for.
    CedarEntitySourceInfo:
      type: object
      required:
      - source-id
      - entity-count
      - config
      properties:
        config:
          $ref: '#/components/schemas/CedarSourceConfig'
          description: Configuration details of the source.
        entity-count:
          type: integer
          format: int64
          description: Number of entities associated with this source.
          minimum: 0
        source-id:
          type: string
          format: uuid
          description: Unique identifier for the entity source.
    CedarResourceConstraintPattern:
      type: object
      description: 'Constraint patterns for filtering policies by resource constraint type.


        Each field corresponds to a Cedar resource constraint pattern.'
      properties:
        eq:
          type: boolean
          description: Include policies with `resource == <ResourceType>::"<id>"` (specific entity)
          default: false
        in:
          type: boolean
          description: 'Include policies with `resource in <ResourceType>::"<id>"` (within hierarchy)

            Also covers `resource is <Path> in <ResourceType>::"<id>"` (typed entity within hierarchy)'
          default: false
        is:
          type: boolean
          description: Include policies with `resource is <ResourceType>` (any entity of this type)
          default: false
    IcebergErrorResponse:
      type: object
      description: JSON wrapper for all error responses (non-2xx)
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorModel'
    ResolveCedarEntitiesResponse:
      type: object
      description: Response from resolving Cedar entities.
      required:
      - entities
      - entity-count
      properties:
        entities:
          type: array
          items: {}
          description: 'Cedar entities in native JSON format.

            Each element represents a Cedar entity with uid, attrs, and parents.'
        entity-count:
          type: integer
          description: Total number of entities resolved.
          minimum: 0
    CedarEffectFilter:
      type: string
      enum:
      - Permit
      - Forbid
    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
    CedarPrincipalConstraintPattern:
      type: object
      description: 'Constraint patterns for filtering policies by principal constraint type.


        Each field corresponds to a Cedar principal constraint pattern.'
      properties:
        eq:
          type: boolean
          description: Include policies with `principal == <PrincipalType>::"<id>"` (specific entity)
          default: false
        in:
          type: boolean
          description: 'Include policies with `principal in <PrincipalType>::"<id>"` (within hierarchy)

            Also covers `principal is <Path> in <PrincipalType>::"<id>"` (typed entity within hierarchy)'
          default: false
        is:
          type: boolean
          description: Include policies with `principal is <PrincipalType>` (any entity of this type)
          default: false
    ListCedarPoliciesQuery:
      type: object
      description: 'Query parameters for listing Cedar policies.


        # Pagination Consistency


        When using pagination with `page_token`, list continuation is only consistent if

        policy sources have not changed between calls. If policy sources are added, removed,

        or modified between paginated requests, results may be incomplete or contain duplicates.'
      properties:
        effect-filter:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/CedarEffectFilter'
            description: 'Filter by effect (permit/forbid).

              If not provided, policies of all effects are returned.'
        page-size:
          type: integer
          description: 'Maximum number of policies to return per page.

            Defaults to 1000 if not specified.'
          minimum: 0
        page-token:
          type:
          - string
          - 'null'
          description: 'Opaque page token from a previous response.

            Use this to retrieve the next page of results.

            The token represents a policy ID to start from.'
        principal-type-filter:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/CedarPrincipalTypeFilter'
            description: 'Filter by principal entity type names.

              Returns policies where the principal scope matches any of these types.'
        resource-type-filter:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/CedarResourceTypeFilter'
            description: 'Filter by resource entity type names.

              Returns policies where the resource scope matches any of these types.'
        source-filter:
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          description: 'Only return policies from the specified source IDs.

            If not provided, policies from all sources are returned.'
    CedarSourceConfig:
      oneOf:
      - allOf:
        - $ref: '#/components/schemas/CedarFileSourceConfig'
        - type: object
          required:
          - source-type
          properties:
            source-type:
              type: string
              enum:
              - file
      - allOf:
        - $ref: '#/components/schemas/CedarKubernetesConfigMapSourceConfig'
        - type: object
          required:
          - source-type
          properties:
            source-type:
              type: string
              enum:
              - kubernetes-config-map
    GetCedarPoliciesResponse:
      type: object
      required:
      - policies
      properties:
        next-page-token:
          type:
          - string
          - 'null'
          description: 'Opaque token for retrieving the next page of results.

            If `None`, there are no more pages to retrieve.'
        policies:
          type: array
          items: {}
          description: 'List of JSON formatted Cedar policies.


            For schema details, see `<https://docs.cedarpolicy.com/policies/json-format.html>`'
    CedarPrincipalTypeFilter:
      type: object
      description: 'Filter for Cedar policy principal constraints.


        This filter allows fine-grained control over which policies to retrieve based on

        their principal scope. Each principal type has its own set of constraint patterns.'
      properties:
        any:
          type: boolean
          description: Include policies where `principal` is unconstrained (applies to all principals)
          default: false
        role:
          oneOf:
          - $ref: '#/components/schemas/CedarPrincipalConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Role` principals
          default:
            eq: false
            in: false
            is: false
        user:
          oneOf:
          - $ref: '#/components/schemas/CedarPrincipalConstraintPattern'
            description: Constraint patterns for `Lakekeeper::User` principals
          default:
            eq: false
            in: false
            is: false
    CedarResourceTypeFilter:
      type: object
      description: 'Filter for Cedar policy resource constraints.


        This filter allows fine-grained control over which policies to retrieve based on

        their resource scope. Each resource type has its own set of constraint patterns.'
      properties:
        any:
          type: boolean
          description: Include policies where `resource` is unconstrained (applies to all resources)
          default: false
        generic-table:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::GenericTable` resources
          default:
            eq: false
            in: false
            is: false
        namespace:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Namespace` resources
          default:
            eq: false
            in: false
            is: false
        project:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Project` resources
          default:
            eq: false
            in: false
            is: false
        role:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Role` resources
          default:
            eq: false
            in: false
            is: false
        server:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Server` resources
          default:
            eq: false
            in: false
            is: false
        table:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Table` resources
          default:
            eq: false
            in: false
            is: false
        user:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::User` resources
          default:
            eq: false
            in: false
            is: false
        view:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::View` resources
          default:
            eq: false
            in: false
            is: false
        warehouse:
          oneOf:
          - $ref: '#/components/schemas/CedarResourceConstraintPattern'
            description: Constraint patterns for `Lakekeeper::Warehouse` resources
          default:
            eq: false
            in: false
            is: false
    CedarFileSourceConfig:
      type: object
      required:
      - file-path
      properties:
        file-path:
          type: string
    ListCedarEntitySourcesResponse:
      type: object
      required:
      - entity-sources
      properties:
        entity-sources:
          type: array
          items:
            $ref: '#/components/schemas/CedarEntitySourceInfo'
    GetCedarSchemaResponse:
      type: object
      required:
      - schema-fragments
      properties:
        schema-fragments:
          type: object
          description: 'The currently active Cedar schema fragments.

            The key is the fragment file path, and the value is the fragment content.'
          additionalProperties:
            type: string
          propertyNames:
            type: string
    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
    CedarResolveResource:
      oneOf:
      - type: string
        enum:
        - server
      - type: object
        required:
        - project
        properties:
          project:
            type: object
            properties:
              project-id:
                type:
                - string
                - 'null'
                description: Project ID. If not specified, the ambient project from the request header is used.
      - type: object
        required:
        - warehouse
        properties:
          warehouse:
            type: object
            required:
            - warehouse-id
            properties:
              warehouse-id:
                type: string
                format: uuid
      - type: object
        required:
        - namespace
        properties:
          namespace:
            allOf:
            - $ref: '#/components/schemas/NamespaceIdentOrUuid'
      - type: object
        required:
        - table
        properties:
          table:
            allOf:
            - $ref: '#/components/schemas/TabularIdentOrUuid'
      - type: object
        required:
        - view
        properties:
          view:
            allOf:
            - $ref: '#/components/schemas/TabularIdentOrUuid'
      - type: object
        required:
        - generic-table
        properties:
          generic-table:
            allOf:
            - $ref: '#/components/schemas/TabularIdentOrUuid'
      description: 'Identifies the resource whose Cedar entity hierarchy should be resolved.


        Mirrors the shape of `CatalogActionCheckOperation` used by the batch-check

        endpoint — externally-tagged enum, reuses [`NamespaceIdentOrUuid`] /

        [`TabularIdentOrUuid`] so callers can address a resource by either UUID or by

        (warehouse + name), matching the rest of the management API.'
    CedarKubernetesConfigMapSourceConfig:
      type: object
      required:
      - configmap-name
      properties:
        configmap-name:
          type: string
    ListCedarPolicySourcesResponse:
      type: object
      required:
      - policy-sources
      properties:
        policy-sources:
          type: array
          items:
            $ref: '#/components/schemas/CedarPolicySourceInfo'
    CedarPolicySourceInfo:
      type: object
      required:
      - source-id
      - policy-count
      - config
      properties:
        config:
          $ref: '#/components/schemas/CedarSourceConfig'
          description: Configuration details of the policy source.
        policy-count:
          type: integer
          format: int64
          description: Number of policies associated with this source.
          minimum: 0
        source-id:
          type: string
          format: uuid
          description: Unique identifier for the policy source.
    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.'
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT