> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/delta-io/delta-sharing/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Temporary Table Credential

> Generate temporary cloud credentials for directory-based table access

## Endpoint

```http theme={null}
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

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication

  ```
  Authorization: Bearer {token}
  ```
</ParamField>

<ParamField header="Content-Type" type="string">
  Optional content type header

  ```
  Content-Type: application/json; charset=utf-8
  ```
</ParamField>

## Path Parameters

<ParamField path="share" type="string" required>
  The share name to query. Case-insensitive.
</ParamField>

<ParamField path="schema" type="string" required>
  The schema name to query. Case-insensitive.
</ParamField>

<ParamField path="table" type="string" required>
  The table name to query. Case-insensitive.
</ParamField>

## Request Body

<ParamField body="location" type="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.
</ParamField>

### Example Request Body

```json theme={null}
{
  "location": "s3://my-bucket/delta-tables/covid_data"
}
```

## Response

### Success Response (200)

<ResponseField name="credentials" type="object" required>
  Temporary credentials object. Only one of `awsTempCredentials`, `azureUserDelegationSas`, or `gcpOauthToken` should be defined.

  <Expandable title="Credentials object">
    <ResponseField name="location" type="string" required>
      The location URL for which these credentials are valid.
    </ResponseField>

    <ResponseField name="awsTempCredentials" type="object">
      AWS temporary credentials (STS tokens). Present for S3 locations.

      <Expandable title="AWS credentials">
        <ResponseField name="accessKeyId" type="string" required>
          AWS access key ID.
        </ResponseField>

        <ResponseField name="secretAccessKey" type="string" required>
          AWS secret access key.
        </ResponseField>

        <ResponseField name="sessionToken" type="string" required>
          AWS session token.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="azureUserDelegationSas" type="object">
      Azure User Delegation SAS token. Present for Azure Blob Storage and ADLS Gen2 locations.

      <Expandable title="Azure credentials">
        <ResponseField name="sasToken" type="string" required>
          Azure SAS token string.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="gcpOauthToken" type="object">
      Google Cloud OAuth token. Present for GCS locations.

      <Expandable title="GCP credentials">
        <ResponseField name="oauthToken" type="string" required>
          GCP OAuth 2.0 token.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="expirationTime" type="integer" required>
      Unix timestamp (milliseconds) when these credentials expire.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Responses

<Tabs>
  <Tab title="AWS S3">
    ```json theme={null}
    {
      "credentials": {
        "location": "s3://my-bucket/delta-tables/covid_data",
        "awsTempCredentials": {
          "accessKeyId": "ASIAXAMPLEACCESSKEY",
          "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
          "sessionToken": "FwoGZXIvYXdzEBYaDH..."
        },
        "expirationTime": 1672531200000
      }
    }
    ```
  </Tab>

  <Tab title="Azure Blob">
    ```json theme={null}
    {
      "credentials": {
        "location": "https://myaccount.blob.core.windows.net/container/delta-tables/covid_data",
        "azureUserDelegationSas": {
          "sasToken": "sv=2021-06-08&ss=b&srt=sco&sp=r&se=2024-01-01T00:00:00Z&st=2023-12-31T00:00:00Z&spr=https&sig=..."
        },
        "expirationTime": 1672531200000
      }
    }
    ```
  </Tab>

  <Tab title="Google Cloud">
    ```json theme={null}
    {
      "credentials": {
        "location": "gs://my-bucket/delta-tables/covid_data",
        "gcpOauthToken": {
          "oauthToken": "ya29.c.b0AXv0zTPW..."
        },
        "expirationTime": 1672531200000
      }
    }
    ```
  </Tab>
</Tabs>

## Error Responses

<Accordion title="400 - Bad Request">
  The request is malformed.

  ```json theme={null}
  {
    "errorCode": "INVALID_PARAMETER_VALUE",
    "message": "Invalid location format"
  }
  ```
</Accordion>

<Accordion title="401 - Unauthorized">
  The request is unauthenticated. The bearer token is missing or incorrect.

  ```json theme={null}
  {
    "errorCode": "UNAUTHENTICATED",
    "message": "Missing or invalid authorization header"
  }
  ```
</Accordion>

<Accordion title="403 - Forbidden">
  The request is forbidden from being fulfilled.

  ```json theme={null}
  {
    "errorCode": "PERMISSION_DENIED",
    "message": "User does not have access to table"
  }
  ```
</Accordion>

<Accordion title="404 - Not Found">
  The requested resource does not exist.

  ```json theme={null}
  {
    "errorCode": "RESOURCE_DOES_NOT_EXIST",
    "message": "Table not found"
  }
  ```
</Accordion>

<Accordion title="500 - Internal Server Error">
  The request is not handled correctly due to a server error.

  ```json theme={null}
  {
    "errorCode": "INTERNAL_ERROR",
    "message": "An internal error occurred"
  }
  ```
</Accordion>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests
  import time

  url = "https://sharing.delta.io/delta-sharing/shares/vaccine_share/schemas/default/tables/covid_data/temporary-table-credentials"
  headers = {
      "Authorization": "Bearer {token}",
      "Content-Type": "application/json"
  }
  data = {
      "location": "s3://my-bucket/delta-tables/covid_data"
  }

  response = requests.post(url, headers=headers, json=data)
  credentials = response.json()["credentials"]

  # Check expiration
  if credentials["expirationTime"] < time.time() * 1000:
      print("Credentials expired, need to refresh")
  else:
      # Use AWS credentials
      aws_creds = credentials["awsTempCredentials"]
      print(f"Access Key: {aws_creds['accessKeyId']}")
  ```

  ```javascript JavaScript theme={null}
  const url = 'https://sharing.delta.io/delta-sharing/shares/vaccine_share/schemas/default/tables/covid_data/temporary-table-credentials';
  const headers = {
    'Authorization': 'Bearer {token}',
    'Content-Type': 'application/json'
  };
  const body = JSON.stringify({
    location: 's3://my-bucket/delta-tables/covid_data'
  });

  fetch(url, { method: 'POST', headers, body })
    .then(response => response.json())
    .then(data => {
      const credentials = data.credentials;
      if (credentials.expirationTime < Date.now()) {
        console.log('Credentials expired, need to refresh');
      } else {
        console.log('AWS Access Key:', credentials.awsTempCredentials.accessKeyId);
      }
    });
  ```
</CodeGroup>

## 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/query-table) API instead.

<Info>
  See [Access Modes](/concepts/access-modes) for a detailed comparison of URL-based and directory-based access patterns.
</Info>

## Notes

<Note>
  Only one of `awsTempCredentials`, `azureUserDelegationSas`, or `gcpOauthToken` should be defined in the response, depending on the cloud storage provider.
</Note>

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>