Skip to content

Conversation

@manisin
Copy link
Contributor

@manisin manisin commented Feb 10, 2026

Summary

Extends the REST Catalog OpenAPI spec to support credential refresh for staged tables by introducing a staging session identifier, following the same pattern as planId for scan planning credential refresh. This addresses an earlier issue raised in community: #13554

  • createTable (POST): When stage-create is true, the LoadTableResult response may now include an optional staging-session field — an opaque session identifier for subsequent credential refresh.
  • loadTable (GET): Accepts an optional stagingSession query parameter to load a staged table and refresh credentials when used with X-Iceberg-Access-Delegation: vended-credentials.
  • loadCredentials (GET): Accepts an optional stagingSession query parameter to refresh credentials for a staged table. Mutually exclusive with planId (returns 400 if both are provided).
  • New reusable staging-session query parameter defined in components/parameters.
  • New staging-session field added to the LoadTableResult schema.

Behavior

When stagingSession is provided:

  • If the session matches a staged table for the given table name, the server returns the response for the staged table.
  • If the session matches a committed table, the server returns the response for the committed table.
  • If the session does not match any staged or committed table, the server returns a 404 error.

When stagingSession is omitted, standard committed table lookup by name is performed.

Backward Compatibility

These changes are fully backward compatible:

  • Existing servers will ignore the stagingSession parameter, maintaining current behavior.
  • Existing clients will not send stagingSession and will function as they do today.
  • ListTables does not expose staged tables — only clients that know the session identifier can access them.

Design

This follows the same pattern as the existing scan planning credential refresh (planId query parameter), where an ID returned from an initial request facilitates stateful credential refreshes for long-running asynchronous operations.

Detailed design: https://docs.google.com/document/d/1R1K6X7qYqvIFkPG3m1neV5Mvy8rwWJvhSFr8DgJgQ-E/edit?tab=t.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant