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

# Rotate a secret

> Replace an OAuth client secret while keeping the credential and catalog names

How-to guideApplies to: Unified engine deployments

Replace an OAuth client secret while keeping the credential and catalog names
used by queries.

## Arrange the remote rotation

Use an existing Polaris catalog with a `retail` warehouse and the SF1 `item`
table in namespace `tpcds_sf1`. Replace the example URLs, client ID, warehouse,
namespace, and Region with your values. The Polaris client needs access to the
warehouse and table. These examples request `PRINCIPAL_ROLE:ALL`; use the scope
granted to your client.

For the final SELECT, Polaris must supply usable temporary S3 credentials for
the table. Otherwise attach a separate storage credential as shown in
[Separate catalog and storage credentials](https://docs.e6data.com/transformation/recipes/credentials/separate-catalog-storage.md).
A successful login or table listing alone does not prove S3 access.

Obtain the current client secret and a replacement from the identity provider.
SQL does not create or revoke Polaris client secrets. Where supported, keep the
old secret active until a query succeeds using the replacement.

## Establish the existing connection

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE SECRET recipe_rotating_secret AS '<current-client-secret>';

CREATE CREDENTIAL recipe_rotating_oauth USING oauth2
OPTIONS (
  'authentication' = 'client_credentials',
  'client_id' = '<client-id>',
  'token_endpoint' = 'https://polaris.example.com/api/catalog/v1/oauth/tokens'
)
SECRETS ('client_secret' = 'recipe_rotating_secret');

CREATE CATALOG recipe_rotating_retail USING `iceberg-rest`
OPTIONS (
  'catalog.type' = 'polaris',
  'uri' = 'https://polaris.example.com/api/catalog',
  'warehouse' = 'retail',
  'auth.type' = 'oauth2',
  'oauth2-server-uri' = 'https://polaris.example.com/api/catalog/v1/oauth/tokens',
  'scope' = 'PRINCIPAL_ROLE:ALL',
  's3.region' = 'us-east-2',
  's3.endpoint' = 'https://s3.us-east-2.amazonaws.com',
  's3.allow-http' = 'false'
)
CREDENTIALS (
  'auth' = 'recipe_rotating_oauth'
);

SELECT i_item_sk, i_item_id
FROM recipe_rotating_retail.tpcds_sf1.item
ORDER BY i_item_sk
LIMIT 5;
```

## Replace the value and check a fresh query

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
ALTER SECRET recipe_rotating_secret SET VALUE '<replacement-client-secret>';
DESCRIBE SECRET recipe_rotating_secret;

SELECT i_item_sk, i_item_id
FROM recipe_rotating_retail.tpcds_sf1.item
ORDER BY i_item_sk
LIMIT 5;
```

The credential resolves the replacement value when it acquires fresh access.
The credential and catalog names stay unchanged. Already running work can retain
access tokens acquired before the change. Revoke the old remote client secret
through its identity provider once you have confirmed the replacement works.

For an external secret, update its remote value outside SQL. If the local
reference pins a version, also [change its version](https://docs.e6data.com/transformation/recipes/secrets/pin-version.md).

When finished:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
DROP CATALOG recipe_rotating_retail;
DROP CREDENTIAL recipe_rotating_oauth;
DROP SECRET recipe_rotating_secret;
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.