IMPORTANT: Developer documentation for the current main branch.
This content is unreleased and may change before the next Polaris release.
For stable user documentation, see the
latest release docs.
Vended Credentials Reference
When an Iceberg client (Spark, Trino, PyIceberg, etc.) loads a table or view, Polaris can be
configured to return short-lived, scoped credentials that the client uses to access cloud storage
directly. These credentials are returned as key-value properties in the Iceberg REST API response
(see LoadTableResult and LoadViewResult in the Iceberg REST
spec).
Properties with kind credential carry sensitive material and are returned in the credentials
map of the API response (never logged). Properties with kind config carry non-sensitive
configuration and are returned in the config map.
There is no standard that defines common property names for vended credentials. The names Polaris uses match what the Iceberg SDK expects for each storage type. This page documents the exact property names Polaris emits so that client authors and operators can diagnose authentication failures and understand client compatibility.
AWS S3🔗
Polaris calls AWS STS AssumeRole
with an inline session policy scoped to the specific table locations and operations (read, list,
write) the caller is authorized to perform. The resulting temporary credentials are returned to the
client.
| Property | Type | Kind | Description |
|---|---|---|---|
s3.access-key-id | String | credential | AWS access key ID from the STS session |
s3.secret-access-key | String | credential | AWS secret access key from the STS session |
s3.session-token | String | credential | AWS session token from the STS session |
s3.session-token-expires-at-ms | String | credential | Expiration time of the session token, in milliseconds since the Unix epoch |
s3.endpoint | String | config | Custom S3 endpoint URL; emitted for S3-compatible stores such as MinIO or Ozone, absent for native AWS S3 |
s3.path-style-access | Boolean | config | Set to true when path-style addressing is required; emitted for S3-compatible stores, absent for native AWS S3 |
client.region | String | config | AWS region to use for S3 and STS requests |
client.refresh-credentials-endpoint | String | config | Catalog endpoint the client can call to refresh vended credentials before they expire |
Azure ADLS🔗
Polaris generates a User Delegation SAS token scoped to the container and path prefix the caller is authorized to access. Azure limits the maximum validity of a User Delegation SAS token to seven days.
| Property | Type | Kind | Description |
|---|---|---|---|
adls.sas-token.<account-host> | String | credential | SAS token keyed by the full storage DNS name (e.g. adls.sas-token.myaccount.dfs.core.windows.net); consumed by Spark via Iceberg’s ADLSFileIO |
adls.sas-token.<account-name> | String | credential | SAS token keyed by the storage account name only (e.g. adls.sas-token.myaccount); consumed by Iceberg 1.7.x clients |
adls.sas-token | String | credential | Bare SAS token (no suffix); consumed by PyIceberg via adlfs/fsspec |
adls.account-name | String | credential | Storage account name; consumed by PyIceberg via adlfs/fsspec |
adls.refresh-credentials-endpoint | String | config | Catalog endpoint the client can call to refresh vended credentials before they expire |
adls.sas-token-expires-at-ms.<account-host> | Long | credential | Expiration time of the SAS token keyed by the full storage DNS name, in milliseconds since the Unix epoch |
📝 Note
The suffixed key forms (adls.sas-token.<account-host> and adls.sas-token.<account-name>) always
carry the same SAS token. Polaris emits all forms simultaneously so that different clients can each
find the key they expect without any client-specific configuration.Google Cloud Storage (GCS)🔗
Polaris obtains a downscoped OAuth2 access token via Google’s Credential Access Boundary mechanism. The token is scoped to the specific GCS buckets and path prefixes the caller is authorized to access and supports optional service account impersonation.
| Property | Type | Kind | Description |
|---|---|---|---|
gcs.oauth2.token | String | credential | Downscoped OAuth2 access token |
gcs.oauth2.token-expires-at | String | credential | Expiration time of the access token, in milliseconds since the Unix epoch |
gcs.oauth2.refresh-credentials-endpoint | String | config | Catalog endpoint the client can call to refresh vended credentials before they expire |
Credential refresh🔗
When a client requests vended credentials by setting the X-Iceberg-Access-Delegation header to
vended-credentials on a table load or create request, Polaris also returns a credential-refresh
endpoint URL in the properties listed above (one per storage type). Iceberg clients that support
the Iceberg REST credential-refresh protocol can call this endpoint to obtain fresh credentials
before the current ones expire, avoiding the need to re-load the table.
Client compatibility summary🔗
The table below summarizes which property forms are required by common clients, based on the Iceberg SDK each client uses.
| Client | Storage type | Required properties |
|---|---|---|
| Apache Spark (Iceberg ≥ 1.8) | S3 | s3.access-key-id, s3.secret-access-key, s3.session-token |
| Apache Spark (Iceberg ≥ 1.8) | ADLS / Blob | adls.sas-token.<account-host> |
| Apache Spark (Iceberg 1.7.x) | ADLS / Blob | adls.sas-token.<account-name> |
PyIceberg (via adlfs / fsspec) | ADLS / Blob | adls.sas-token, adls.account-name |
| Apache Spark / PyIceberg | GCS | gcs.oauth2.token |
Polaris emits all applicable forms simultaneously, so no client-specific Polaris configuration is required to switch between the clients listed above.