> ## 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.

# Use OAuth client credentials

> Give the engine a client ID and a client-secret reference. It exchanges them for

How-to guideApplies to: Unified engine deployments

Give the engine a client ID and a client-secret reference. It exchanges them for
an access token when the catalog needs one. This recipe uses Polaris.

## Prepare the OAuth client

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.

Create the OAuth client and obtain its client secret outside SQL. Ensure the
engine can reach both the token endpoint and catalog API over HTTPS. The local
encrypted secret store must be available.

## Create the OAuth credential

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

CREATE CREDENTIAL recipe_oauth_auth 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_oauth_secret');
```

The secret is the client's password, not an access token. The fixed token
endpoint must match the endpoint configured by its consuming catalog.

## Connect and read

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE CATALOG recipe_oauth_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_oauth_auth'
);

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

The catalog supplies the token scope for this connection. A credential can also
have `scopes`, `audience`, and `resource` options when required by its token
service. Acquired OAuth tokens can be renewed while the client secret and
remote permissions remain valid.

When finished:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
DROP CATALOG recipe_oauth_retail;
DROP CREDENTIAL recipe_oauth_auth;
DROP SECRET recipe_oauth_secret;
```


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