# Authenticate to Redpanda SQL

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt)

---
title: Authenticate to Redpanda SQL
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-connect-version: 4.93.0
latest-redpanda-tag: v26.1.9
docname: connect-to-sql/authenticate
page-component-name: cloud-data-platform
page-version: master
page-component-version: master
page-component-title: Cloud
page-relative-src-path: connect-to-sql/authenticate.adoc
page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/sql/pages/connect-to-sql/authenticate.adoc
description: Authenticate to Redpanda SQL with an OIDC bearer token, OIDC client credentials, or a SCRAM username and password for legacy clients.
page-topic-type: how-to
personas: app_developer, data_engineer, platform_admin
learning-objective-1: Connect to Redpanda SQL with an OIDC bearer token or client credentials
learning-objective-2: Set up a SCRAM username and password so a legacy client can connect to Redpanda SQL
page-git-created-date: "2026-05-26"
page-git-modified-date: "2026-05-26"
---

<!-- Source: https://docs.redpanda.com/cloud-data-platform/sql/connect-to-sql/authenticate.md -->

Authenticate to Redpanda SQL with an [OpenID Connect (OIDC)](https://docs.redpanda.com/cloud-data-platform/reference/glossary/#openid-connect-oidc) bearer token, OIDC client credentials, or a SCRAM password for clients that don’t support OIDC. For how an admin grants users access to topics and catalogs, see [Manage Access to Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/manage/manage-access/).

After completing these steps, you will be able to:

-   Connect to Redpanda SQL with an OIDC bearer token or client credentials

-   Set up a SCRAM username and password so a legacy client can connect to Redpanda SQL


## [](#prerequisites)Prerequisites

-   A Redpanda BYOC cluster on AWS with Redpanda SQL enabled. See [Enable Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/get-started/deploy-sql-cluster/).

-   [`psql`](https://www.postgresql.org/download/) or another PostgreSQL-compatible client.

-   A user or service account assigned a role with the **SQL: Access** or **SQL: Manage** permission in Redpanda Cloud’s data-plane RBAC. Redpanda Cloud provisions a corresponding user in the SQL engine when the role is assigned. To assign roles, go to **Organization IAM > Roles**; SQL permissions are under the **Data Plane** tab when you create or edit a role. See [Configure RBAC in the Data Plane](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/rbac_dp/).


## [](#authentication-modes)Authentication modes

Redpanda SQL supports three authentication modes, selected by the connection-string `options` parameter:

| Mode | options value | When to use |
| --- | --- | --- |
| Bearer token | auth_method=bearer | You already hold a JSON Web Token (JWT) issued by Redpanda Cloud (for example, returned by rpk cloud auth token). |
| Client credentials | auth_method=client_secret | Service-to-service connections (scheduled jobs, BI tools). Redpanda SQL exchanges a Redpanda Cloud service account’s client ID and client secret for a token against Redpanda Cloud’s token endpoint, then validates the returned token. |
| SCRAM password | (omit options) | Legacy clients that don’t support bearer-token or client-credentials authentication. The username is the Redpanda Cloud account or service account email; the password is set by a SQL: Manage user with ALTER USER. See Connect with SCRAM for legacy clients. |

Redpanda SQL treats a [bearer token](https://docs.redpanda.com/cloud-data-platform/reference/glossary/#bearer-token) in the password field without `auth_method=bearer` as a SCRAM password, and the connection fails. To use a bearer token, you must set `options='auth_method=bearer'`.

## [](#connect-with-a-bearer-token)Connect with a bearer token

Use bearer-token authentication for human users who hold a JWT issued by Redpanda Cloud. Run `rpk cloud auth token` to obtain a token you can pass directly; see [Quickstart](https://docs.redpanda.com/cloud-data-platform/sql/get-started/sql-quickstart/) for the end-to-end setup.

Set `options='auth_method=bearer'` in the connection string and pass the token in the password field. Redpanda SQL ignores the `user=` field and takes the session identity from the principal claim in the token.

psql

```bash
PGPASSWORD=$(rpk cloud auth token) \
  psql "host=<sql-host> port=<sql-port> dbname=oxla user=ignored options='auth_method=bearer' sslmode=require"
```

Python (psycopg2)

```python
import os
import psycopg2

# Set BEARER_TOKEN before running, for example:
#   export BEARER_TOKEN=$(rpk cloud auth token)
conn = psycopg2.connect(
    host="<sql-host>",
    port=<sql-port>,
    dbname="oxla",
    user="ignored",
    password=os.environ["BEARER_TOKEN"],
    options="auth_method=bearer",
    sslmode="require",
)

cur = conn.cursor()
cur.execute("SELECT current_user")
# current_user is the principal from the token, not "ignored"
```

For more language-client examples, see [Connect to Redpanda SQL](../).

## [](#connect-with-client-credentials)Connect with client credentials

Use client-credentials authentication for service-to-service connections: scheduled jobs, BI tools, or other automated clients that can’t perform interactive sign-in. Each Redpanda Cloud service account has a client ID and client secret; Redpanda SQL exchanges those credentials for a token against Redpanda Cloud’s token endpoint and validates it.

Set `options='auth_method=client_secret'`, pass the Redpanda Cloud service account’s client ID in `user=`, and the client secret in the password field. The resolved principal becomes the session identity.

```bash
PGPASSWORD="$CLIENT_SECRET" \
  psql "host=<sql-host> port=<sql-port> dbname=oxla user=<client-id> options='auth_method=client_secret' sslmode=require"
```

## [](#connect-with-scram-for-legacy-clients)Connect with SCRAM for legacy clients

For applications and tools that don’t support OIDC, set a SCRAM username and password directly on the user’s account in Redpanda SQL. The legacy client then connects with that username and password.

This path still relies on Redpanda Cloud to provision the user in the SQL engine. Cloud’s auto-provisioning generates an internal password that is not exposed to you, so a **SQL: Manage** user must explicitly set a known password with `ALTER USER` before the legacy client can sign in.

1.  In Redpanda Cloud, create or designate a service account for the legacy client, then assign it the **SQL: Access** (or **SQL: Manage**) data-plane RBAC permission. Redpanda Cloud provisions a corresponding user in the SQL engine. See [Configure RBAC in the Data Plane](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/rbac_dp/).

2.  As a **SQL: Manage** user, set a known password on the provisioned account. The username is the email on the service account:

    ```sql
    ALTER USER "service-account@example.com" WITH PASSWORD 'shared_secret';
    ```

3.  Configure the legacy client to connect with that username and password. Do not set the `auth_method` option:

    ```bash
    PGPASSWORD='shared_secret' \
      psql "host=<sql-host> port=<sql-port> dbname=oxla user=service-account@example.com sslmode=require"
    ```


`ALTER USER …​ WITH PASSWORD` persists across cluster operations: Redpanda Cloud’s user reconciler only changes a role’s superuser attribute or revokes access, never resets the password. If the service account loses its **SQL: Access** (or **SQL: Manage**) role assignment in Redpanda Cloud, however, the reconciler revokes `CONNECT` and the legacy client can no longer sign in.

## [](#use-tls-on-connections)Use TLS on connections

Credentials travel in the password field of the PostgreSQL startup message, whether you authenticate with a bearer token, client credentials, or a SCRAM password. To protect them in transit, set `sslmode=require` on every connection.

On Redpanda Cloud BYOC, the SQL endpoint requires TLS. Connections without TLS are rejected by the server.

## [](#reconnect-when-a-token-expires)Reconnect when a token expires

OIDC bearer tokens are short-lived. Redpanda SQL validates the token once at connection time and does not re-validate it over the lifetime of the session. After the token expires, the database session continues until it closes for some other reason, but new connections must present a fresh token. Run `rpk cloud auth token` to obtain a new token, then reconnect.

## [](#next-steps)Next steps

-   [Manage access](https://docs.redpanda.com/cloud-data-platform/sql/manage/manage-access/): how the admin grants per-user access after authentication.

-   [Connect to Redpanda SQL](../): language-client connection guides.