Skip to main content

​
Endpoint

POST {prefix}/shares/{share}/schemas/{schema}/tables/{table}/temporary-table-credentials
This API returns Cloud Tokens, which are directory (prefix) based STS tokens that grant temporary read access to the table’s root directory. This approach bypasses the pre-signing workflow and instead provides direct read-only access to the table. Query engines that are capable of processing the delta log get direct access to it and can optimize query performance by leveraging their custom metadata optimizations, caching, and distributed metadata processing.

​
Authentication

​
Authorization
string
required
Bearer token for authentication
Authorization: Bearer {token}
​
Content-Type
string
Optional content type header
Content-Type: application/json; charset=utf-8

​
Path Parameters

​
share
string
required
The share name to query. Case-insensitive.
​
schema
string
required
The schema name to query. Case-insensitive.
​
table
string
required
The table name to query. Case-insensitive.

​
Request Body

​
location
string
Optional location URL path to generate temporary credentials for.This API should be called for the root location as well as all the auxiliary locations. If a table has auxiliary locations and a client does not support reading from multiple locations, they should either fall back to URL-based access via the Query Table API or throw an error.If this field is not provided, the response should contain credentials for the table’s main location.

​
Example Request Body

{
  "location": "s3://my-bucket/delta-tables/covid_data"
}

​
Response

​
Success Response (200)

​
credentials
object
required
Temporary credentials object. Only one of awsTempCredentials, azureUserDelegationSas, or gcpOauthToken should be defined.

​
Example Responses

{
  "credentials": {
    "location": "s3://my-bucket/delta-tables/covid_data",
    "awsTempCredentials": {
      "accessKeyId": "ASIAXAMPLEACCESSKEY",
      "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "sessionToken": "FwoGZXIvYXdzEBYaDH..."
    },
    "expirationTime": 1672531200000
  }
}

​
Error Responses

The request is malformed.
{
  "errorCode": "INVALID_PARAMETER_VALUE",
  "message": "Invalid location format"
}
The request is unauthenticated. The bearer token is missing or incorrect.
{
  "errorCode": "UNAUTHENTICATED",
  "message": "Missing or invalid authorization header"
}
The request is forbidden from being fulfilled.
{
  "errorCode": "PERMISSION_DENIED",
  "message": "User does not have access to table"
}
The requested resource does not exist.
{
  "errorCode": "RESOURCE_DOES_NOT_EXIST",
  "message": "Table not found"
}
The request is not handled correctly due to a server error.
{
  "errorCode": "INTERNAL_ERROR",
  "message": "An internal error occurred"
}

​
Usage Example

curl -X POST \
  https://sharing.delta.io/delta-sharing/shares/vaccine_share/schemas/default/tables/covid_data/temporary-table-credentials \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "s3://my-bucket/delta-tables/covid_data"
  }'

​
Access Modes

This API is part of the directory-based access mode. For tables that support this mode:
  1. The table metadata will include "dir" in the accessModes array
  2. The location field will be present in the table metadata
  3. Clients can use this API to get temporary credentials for direct access to the Delta log and data files
For tables that only support URL-based access, use the Query Table API instead.
See Access Modes for a detailed comparison of URL-based and directory-based access patterns.

​
Notes

Only one of awsTempCredentials, azureUserDelegationSas, or gcpOauthToken should be defined in the response, depending on the cloud storage provider.
If a table has auxiliaryLocations, you must call this API separately for each location (the main location and all auxiliary locations) to get the appropriate credentials.
Query engines capable of processing the Delta log can use these credentials to optimize query performance through custom metadata optimizations, caching, and distributed metadata processing.

Build docs developers (and LLMs) love

Get started for freeTalk to us