# Redshift Redshift API

Source: https://userguide.qualytics.io/source-datastore/datastore/jdbc/redshift/how-tos/api/

This page documents Redshift-specific payload fields for the datastore API. For generic operations (get, list, update, delete, multi-schema bulk), see [Datastore API](https://userguide.qualytics.io/source-datastore/datastore/api/).

> **Tip: Complete API Reference**
>
> For the full interactive API documentation with all request and response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

Redshift supports three authentication types (**Password** by default, **IAM Role**, or **Assumed Role**, which works like IAM Role) and can be created as a source datastore (read-only) or an enrichment datastore (read-write). You can create a datastore with a new inline connection or reuse an existing connection. All flows use the same endpoint:

**Endpoint**: `POST /api/datastores`

**Permission**: Manager, plus the **Editor** team permission on at least one of the assigned teams (the **Public** team when `teams` is left out). Admins are exempt.

---

## UI ↔ API field mapping

The API names a few fields differently from the UI. The mapping below avoids the most common copy-paste mistakes when switching from the form to the JSON payload.

| UI form field | API field | Notes | Example |
| --- | --- | --- | --- |
| **Connection > Connection Name** | `connection.name` | Saved-connection label. Optional. | `redshift_production` |
| (set by connector choice) | `connection.type` | Connector identifier. Always `"redshift"` for Redshift. | `redshift` |
| **Connection > Host** | `connection.host` | Cluster endpoint hostname. | `your-cluster.abc123.us-east-1.redshift.amazonaws.com` |
| **Connection > Port** | `connection.port` | Integer. Defaults to `5439`. | `5439` |
| **Datastore > Database** | `database` | The Redshift database (top-level in payload, not under `connection`). | `your_database` |
| **Datastore > Schema** | `schema` | The Redshift schema (top-level). | `public` |
| **Connection > Type** | `connection.parameters.authentication_type` | `BASIC` (Password) or `IAM_ROLE`. Defaults to `BASIC` when omitted. | `BASIC` |
| **Connection > User** | `connection.username` | Redshift database user. Required only when `authentication_type` is `BASIC`. | `qualytics_read` |
| **Connection > Password** | `connection.password` | Redshift database password. Required only when `authentication_type` is `BASIC`. | `...` |
| **Connection > Role ARN** | `connection.parameters.role_arn` | Target role for STS AssumeRole. Required when `authentication_type` is `IAM_ROLE`. | `arn:aws:iam::123456789012:role/MyRole` |
| **Connection > External ID** | `connection.parameters.external_id` | Optional external ID enforced by the role's trust policy. | `<your-external-id>` |
| **Connection > Database User** | `connection.parameters.db_user` | Optional. Redshift database user the temporary credentials are issued for on a provisioned cluster. Defaults to `spark` when omitted. Available when `authentication_type` is `IAM_ROLE` or `ASSUMED_ROLE`. | `qualytics_enrichment` |
| **Datastore > Initiate Sync** | `trigger_sync` | When `true`, syncs metadata immediately after creation. | `true` |

When `authentication_type` is `IAM_ROLE`, omit `username` and `password` from the payload. Qualytics rewrites the JDBC URL to `jdbc:redshift:iam://` automatically and obtains short-lived database credentials through the JDBC driver. On a provisioned cluster those credentials are issued for `parameters.db_user`, or for `spark` when it is omitted.

## Connection Fields

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `host` | string | Yes |  | Redshift cluster endpoint hostname. |
| `port` | integer | No | `5439` | Redshift listening port. |
| `database` | string | Yes |  | The Redshift database name (top-level, not under `connection`). |
| `schema` | string | Yes |  | The Redshift schema name (top-level). |
| `parameters.authentication_type` | string | No | `BASIC` | `BASIC` (Password), `IAM_ROLE`, or `ASSUMED_ROLE`. |
| `parameters.role_arn` | string | If `IAM_ROLE` or `ASSUMED_ROLE` |  | IAM role ARN to assume via AWS STS. |
| `parameters.external_id` | string | No |  | External ID for STS AssumeRole. Include only when your trust policy requires one. |
| `parameters.db_user` | string | No | `spark` | Redshift database user the temporary IAM credentials are issued for on a provisioned cluster. Ignored with `BASIC` and on Serverless. |
| `username` | string | If `BASIC` |  | Redshift database user. |
| `password` | string | If `BASIC` |  | Redshift database password. |

> **Note: About trigger_sync**
>
> The `trigger_sync: true` flag in the examples below tells Qualytics to immediately sync metadata after creating the datastore (equivalent to ticking the **Initiate Sync** toggle in the UI). Set it to `false` if you want to defer the first sync.

---

## Create a Source Datastore

A source datastore uses a read-only Redshift user (Password mode) or a target IAM role (IAM Role mode). Set `enrichment_only: false` to mark the datastore as a source.

**Tab: Password (New Connection)**

Use this mode when you can supply a Redshift database user and password directly. Pass the credentials as `username` and `password`, and set `authentication_type` to `BASIC` (or omit `parameters` entirely, since `BASIC` is the default).

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Redshift Production",
>     "connection": {
>       "name": "redshift_production",
>       "type": "redshift",
>       "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
>       "port": 5439,
>       "username": "your_user",
>       "password": "your_password",
>       "parameters": {
>         "authentication_type": "BASIC"
>       }
>     },
>     "database": "your_database",
>     "schema": "public",
>     "teams": ["Data Platform"],
>     "enrichment_only": false,
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 42,
>   "name": "Redshift Production",
>   "type": "redshift",
>   "store_type": "jdbc",
>   "database": "your_database",
>   "schema": "public",
>   "enrichment_only": false,
>   "connected": true
> }
> ```

**Tab: IAM Role (New Connection)**

Authenticate via AWS STS by assuming an IAM role. Qualytics obtains short-lived database credentials that refresh automatically. Use this mode for cross-account access, environments that disallow long-lived database passwords, or to centralize Redshift access in IAM. Set `parameters.authentication_type` to `"IAM_ROLE"` and provide the role ARN. Omit `username` and `password`. The `external_id` field is optional and only required if your trust policy enforces it. `parameters.db_user` is optional as well: it names the provisioned-cluster database user the temporary credentials are issued for, and defaults to `spark`.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Redshift Production",
>     "connection": {
>       "name": "redshift_production",
>       "type": "redshift",
>       "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
>       "port": 5439,
>       "parameters": {
>         "authentication_type": "IAM_ROLE",
>         "role_arn": "arn:aws:iam::123456789012:role/QualyticsRedshiftRole",
>         "external_id": "<your-external-id>"
>       }
>     },
>     "database": "your_database",
>     "schema": "public",
>     "teams": ["Data Platform"],
>     "enrichment_only": false,
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 42,
>   "name": "Redshift Production",
>   "type": "redshift",
>   "store_type": "jdbc",
>   "database": "your_database",
>   "schema": "public",
>   "enrichment_only": false,
>   "connected": true
> }
> ```

> **Note**
>
> See [Authentication](https://userguide.qualytics.io/source-datastore/datastore/jdbc/redshift/authentication/) and [IAM Role Authentication](https://userguide.qualytics.io/deployments/iam-role-authentication/) for the trust policy setup and per-deployment base role details.

> **Note: Assumed Role**
>
> The **Type** selector also offers **Assumed Role**. Send the same payload with `parameters.authentication_type` set to `"ASSUMED_ROLE"`: it takes the same `role_arn`, optional `external_id` and optional `db_user`, and Qualytics handles it the same way.

**Tab: Existing Connection**

Reuse a previously created Redshift connection (via this API or the UI) by passing its `connection_id` at the top level instead of inlining `connection: {...}`. The authentication type and credentials are reused from the existing connection. You only specify datastore-level fields like `database`, `schema`, `teams`, and `enrichment_only`.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Redshift Finance",
>     "connection_id": 7,
>     "database": "your_database",
>     "schema": "finance",
>     "teams": ["Finance Team"],
>     "enrichment_only": false,
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 43,
>   "name": "Redshift Finance",
>   "type": "redshift",
>   "store_type": "jdbc",
>   "database": "your_database",
>   "schema": "finance",
>   "enrichment_only": false,
>   "connected": true
> }
> ```

---

## Create an Enrichment Datastore

An enrichment datastore uses a read-write Redshift user (Password mode) or a target IAM role with both the read and the write grants. Set `enrichment_only: true` to create the datastore for enrichment.

**Tab: Password (New Connection)**

Use a read-write Redshift user that holds the source grants plus the additional `CREATE`, `INSERT`, `UPDATE`, and `DELETE` privileges on the enrichment schema. Pass the credentials as `username` and `password`.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Redshift Enrichment",
>     "connection": {
>       "name": "redshift_enrichment",
>       "type": "redshift",
>       "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
>       "port": 5439,
>       "username": "qualytics_readwrite",
>       "password": "your_password",
>       "parameters": {
>         "authentication_type": "BASIC"
>       }
>     },
>     "database": "your_database",
>     "schema": "qualytics_enrichment",
>     "teams": ["Data Platform"],
>     "enrichment_only": true,
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 44,
>   "name": "Redshift Enrichment",
>   "type": "redshift",
>   "store_type": "jdbc",
>   "database": "your_database",
>   "schema": "qualytics_enrichment",
>   "enrichment_only": true,
>   "connected": true
> }
> ```

**Tab: IAM Role (New Connection)**

Set `parameters.authentication_type` to `"IAM_ROLE"`, provide the role ARN, and set `parameters.db_user` to the Redshift user that holds the enrichment grants (omit it to use `spark`). Omit `username` and `password`. The `external_id` field is optional and only required if your trust policy enforces it.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Redshift Enrichment",
>     "connection": {
>       "name": "redshift_enrichment",
>       "type": "redshift",
>       "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
>       "port": 5439,
>       "parameters": {
>         "authentication_type": "IAM_ROLE",
>         "role_arn": "arn:aws:iam::123456789012:role/QualyticsRedshiftEnrichmentRole",
>         "external_id": "<your-external-id>",
>         "db_user": "qualytics_enrichment"
>       }
>     },
>     "database": "your_database",
>     "schema": "qualytics_enrichment",
>     "teams": ["Data Platform"],
>     "enrichment_only": true,
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 44,
>   "name": "Redshift Enrichment",
>   "type": "redshift",
>   "store_type": "jdbc",
>   "database": "your_database",
>   "schema": "qualytics_enrichment",
>   "enrichment_only": true,
>   "connected": true
> }
> ```

> **Warning: Enrichment IAM Role permissions**
>
> The assumed role needs the AWS IAM permissions for credential issuance (provisioned: `redshift:GetClusterCredentials` and `redshift:CreateClusterUser` on the `dbuser` resource for `spark`, or for the `parameters.db_user` you send, and on Serverless, `redshift-serverless:GetCredentials`) plus the DB-level enrichment grants (`CREATE`, `INSERT`, `UPDATE`, `DELETE`) on the target schema. See [Permissions](https://userguide.qualytics.io/source-datastore/datastore/jdbc/redshift/permissions/#aws-iam-permissions-iam-role-and-assumed-role-modes) for the full IAM policy.

> **Note: Assumed Role**
>
> The **Type** selector also offers **Assumed Role**. Send the same payload with `parameters.authentication_type` set to `"ASSUMED_ROLE"`: it takes the same `role_arn`, optional `external_id` and optional `db_user`, and Qualytics handles it the same way.

**Tab: Existing Connection**

Reuse a previously created Redshift connection that was configured for read-write access. Pass `connection_id` and set `enrichment_only: true`.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/datastores" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Redshift Enrichment",
>     "connection_id": 7,
>     "database": "your_database",
>     "schema": "qualytics_enrichment",
>     "teams": ["Data Platform"],
>     "enrichment_only": true,
>     "trigger_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 45,
>   "name": "Redshift Enrichment",
>   "type": "redshift",
>   "store_type": "jdbc",
>   "database": "your_database",
>   "schema": "qualytics_enrichment",
>   "enrichment_only": true,
>   "connected": true
> }
> ```

---

## Other Operations

For get, list, update, delete, test connection, and link-enrichment endpoints, see the [Datastore API](https://userguide.qualytics.io/source-datastore/datastore/api/) reference.

*Last updated: November 3, 2026.*
