Redshift User Management API Guide

Auth method: AWS Signature Version 4 (SigV4) – IAM credentials (Access Key ID + Secret Access Key + optional Session Token)

Setup steps

1. Create an IAM user or role with the required Redshift IAM permissions (e.g., redshift:GetClusterCredentials, redshift:CreateClusterUser).
2. Attach an IAM policy granting the specific Redshift API actions needed.
3. Generate AWS Access Key ID and Secret Access Key for the IAM principal (or use an IAM role with STS AssumeRole for temporary credentials).
4. Sign all API requests using AWS Signature Version 4 with the target region and service name 'redshift'.
5. For federated/SSO users, configure AWS IAM Identity Center with SAML 2.0 and enable SCIM provisioning from your IdP.

Required scopes

Get Temporary Database Credentials

• Method: POST
• URL: https://redshift.{region}.amazonaws.com/?Action=GetClusterCredentials
• Watch out for: AutoCreate=true requires the IAM policy to include redshift:CreateClusterUser. The returned DbUser will have an 'IAM:' prefix in the database.

Request example

Action=GetClusterCredentials
&ClusterIdentifier=my-cluster
&DbUser=myuser
&DbName=mydb
&AutoCreate=true
&DurationSeconds=3600
&Version=2012-12-01

Response example

{
  "DbUser": "IAM:myuser",
  "DbPassword": "AMAz...",
  "Expiration": "2024-01-01T12:00:00Z"
}

Get Temporary Credentials (IAM Identity Center / SSO)

• Method: POST
• URL: https://redshift.{region}.amazonaws.com/?Action=GetClusterCredentialsWithIAM
• Watch out for: Uses the caller's IAM identity directly; does not accept DbUser parameter. Federated users get 'IAMA:' prefix.

Request example

Action=GetClusterCredentialsWithIAM
&ClusterIdentifier=my-cluster
&DbName=mydb
&DurationSeconds=900
&Version=2012-12-01

Response example

{
  "DbUser": "IAMA:myuser",
  "DbPassword": "AMAz...",
  "Expiration": "2024-01-01T12:15:00Z"
}

Describe Clusters

• Method: POST
• URL: https://redshift.{region}.amazonaws.com/?Action=DescribeClusters
• Watch out for: Returns cluster-level metadata including MasterUsername but does not enumerate individual database users. Use SQL (pg_user) for that.

Request example

Action=DescribeClusters
&ClusterIdentifier=my-cluster
&Version=2012-12-01

Response example

{
  "Clusters": [{
    "ClusterIdentifier": "my-cluster",
    "MasterUsername": "admin",
    "ClusterStatus": "available"
  }]
}

Modify Cluster (reset master password)

• Method: POST
• URL: https://redshift.{region}.amazonaws.com/?Action=ModifyCluster
• Watch out for: Password change is asynchronous; cluster enters 'modifying' state. Only the master user password can be changed via API; other DB users must be managed via SQL.

Request example

Action=ModifyCluster
&ClusterIdentifier=my-cluster
&MasterUserPassword=NewP%40ssw0rd!
&Version=2012-12-01

Response example

{
  "Cluster": {
    "ClusterIdentifier": "my-cluster",
    "ClusterStatus": "modifying"
  }
}

Create Cluster (with master user)

• Method: POST
• URL: https://redshift.{region}.amazonaws.com/?Action=CreateCluster
• Watch out for: MasterUsername is immutable after creation. All other database users must be created via SQL after the cluster is available.

Request example

Action=CreateCluster
&ClusterIdentifier=my-cluster
&MasterUsername=admin
&MasterUserPassword=P%40ssw0rd!
&NodeType=dc2.large
&NumberOfNodes=2
&DBName=mydb
&Version=2012-12-01

Response example

{
  "Cluster": {
    "ClusterIdentifier": "my-cluster",
    "MasterUsername": "admin",
    "ClusterStatus": "creating"
  }
}

Get Serverless Credentials

• Method: POST
• URL: https://redshift-serverless.{region}.amazonaws.com/?Action=GetCredentials
• Watch out for: Serverless uses a separate API endpoint (redshift-serverless) and a different API version. WorkgroupName replaces ClusterIdentifier.

Request example

Action=GetCredentials
&WorkgroupName=my-workgroup
&DbName=mydb
&DurationSeconds=900
&Version=2021-01-01

Response example

{
  "DbUser": "IAMA:myuser",
  "DbPassword": "AMAz...",
  "Expiration": "2024-01-01T12:15:00Z"
}

List Cluster Users (SQL-only)

• Method: GET
• URL: N/A – SQL only
• Watch out for: There is no Redshift management API endpoint to list database users. User enumeration requires a SQL query against pg_user or SVL_USER_INFO via a database connection.

Request example

SELECT usename, usecreatedb, usesuper
FROM pg_user;

Response example

usename       | usecreatedb | usesuper
--------------+-------------+---------
admin         | t           | t
IAM:jdoe      | f           | f

Associate IAM Role with Cluster

• Method: POST
• URL: https://redshift.{region}.amazonaws.com/?Action=ModifyClusterIamRoles
• Watch out for: IAM roles are attached at the cluster level for data operations (COPY/UNLOAD), not for individual database user permissions. Per-user permissions are managed via SQL GRANT statements.

Request example

Action=ModifyClusterIamRoles
&ClusterIdentifier=my-cluster
&AddIamRoles.member.1=arn:aws:iam::123456789012:role/MyRole
&Version=2012-12-01

Response example

{
  "Cluster": {
    "ClusterIdentifier": "my-cluster",
    "IamRoles": [{"IamRoleArn": "arn:aws:iam::123456789012:role/MyRole"}]
  }
}

• Rate limits: Amazon Redshift API calls are subject to AWS service quotas. There is no publicly documented per-second rate limit for Redshift management API calls; limits are enforced via AWS service quotas and may result in ThrottlingException responses.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: AWS does not document specific rate-limit headers for Redshift API responses. Clients should implement exponential backoff on ThrottlingException errors per AWS SDK retry guidance.
• Pagination method: token
• Default page size: 100
• Max page size: 100
• Pagination pointer: Marker

• Webhooks available: No
• Webhook notes: Amazon Redshift does not offer webhooks for user management events. Event notifications are available via Amazon SNS for cluster-level events (e.g., cluster created, modified) but not for database user lifecycle events.
• Alternative event strategy: Use Amazon EventBridge with CloudTrail to capture Redshift API calls (e.g., GetClusterCredentials) as events for audit or automation purposes.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: AWS IAM Identity Center (free AWS service; requires enabling IAM Identity Center and configuring an external IdP or using AWS SSO directory)

• Endpoint: SCIM endpoint is IdP-specific and generated by AWS IAM Identity Center during automatic provisioning setup (format: https://scim.{region}.amazonaws.com/{tenantId}/scim/v2/). Not a Redshift-native endpoint.

• Supported operations: Create User, Update User, Deactivate User, Create Group, Update Group membership, Delete Group

Limitations:

• SCIM provisions users into IAM Identity Center, not directly into Redshift database users. Redshift database user creation still occurs on first login via GetClusterCredentialsWithIAM with AutoCreate.
• Requires SAML 2.0 SSO to be configured between the IdP and IAM Identity Center before SCIM can be enabled.
• Supported IdPs with documented SCIM integration: Okta, Microsoft Entra ID (Azure AD), OneLogin.
• Google Workspace is not listed as a supported SCIM provider for IAM Identity Center.
• Deprovisioning a user in IAM Identity Center does not automatically drop the database user from Redshift; SQL DROP USER must be executed separately.
• SCIM endpoint URL and bearer token are generated per IAM Identity Center instance and must be configured in the IdP.

Three scenarios cover the majority of programmatic user lifecycle needs:

• Federated first-login provisioning: Configure SAML 2.0 between the IdP and IAM Identity Center, enable SCIM automatic provisioning, then call GetClusterCredentialsWithIAM with AutoCreate=true on first access. The database user is created with an IAMA: prefix at credential generation time - not at SCIM sync time. Any SQL GRANTs intended to pre-provision the user must reference the IAMA:username format before the user physically exists in the database, or be applied post-first-login.

• Deprovisioning: Deactivate the user in the IdP; SCIM syncs the deactivation to IAM Identity Center, blocking new credential generation. Existing temporary credentials remain valid until DurationSeconds expires (max 3600s). SQL REVOKE and DROP USER must then be executed separately - this cannot be triggered via the management API. The recommended pattern is an EventBridge rule on the IAM Identity Center deactivation event, invoking a Lambda function that connects to the cluster and executes the SQL cleanup.

• Master password rotation: Call ModifyCluster with the new MasterUserPassword. The operation is asynchronous; poll DescribeClusters until ClusterStatus returns to 'available' before using the new credentials. AWS Secrets Manager with automatic Redshift rotation is the lower-risk alternative to managing this manually.

Federated SSO user accesses Redshift for the first time

1. Configure SAML 2.0 between IdP (e.g., Okta) and AWS IAM Identity Center.
2. Enable SCIM automatic provisioning in IAM Identity Center; configure the IdP with the generated SCIM endpoint URL and bearer token.
3. Assign the user to the Redshift application in the IdP; SCIM syncs the user to IAM Identity Center.
4. User authenticates via IdP; receives a SAML assertion exchanged for temporary AWS credentials via STS.
5. Application calls GetClusterCredentialsWithIAM (or GetClusterCredentials with AutoCreate=true) to obtain temporary database credentials.
6. Redshift auto-creates the database user with 'IAMA:' prefix on first credential generation.
7. Application connects to Redshift using the temporary DbUser and DbPassword.

Watch out for: The database user is not created until the first GetClusterCredentials call. Pre-provisioning SQL grants must reference the 'IAMA:username' format before the user exists, or be applied after first login.

Deprovision a user when they leave the organization

1. Deactivate or delete the user in the IdP; SCIM syncs the deactivation to IAM Identity Center.
2. IAM Identity Center revokes the user's SSO access; they can no longer obtain new temporary credentials.
3. Existing temporary credentials expire within their DurationSeconds window (max 3600s).
4. Connect to the Redshift cluster as a superuser and execute: REVOKE ALL ON ALL TABLES IN SCHEMA public FROM "IAMA:username";
5. Execute: DROP USER "IAMA:username"; to remove the database user.

Watch out for: Steps 4–5 are SQL-only and cannot be performed via the Redshift management API. Automate them via a Lambda function triggered by an EventBridge rule on the IAM Identity Center user deactivation event.

Programmatically rotate master user password

1. Ensure the calling IAM principal has redshift:ModifyCluster permission on the target cluster.
2. Call ModifyCluster with the new MasterUserPassword value.
3. Poll DescribeClusters until ClusterStatus returns to 'available' (cluster enters 'modifying' state during rotation).
4. Update any secrets manager entries (e.g., AWS Secrets Manager) storing the master password.
5. Verify connectivity with the new credentials.

Watch out for: ModifyCluster is asynchronous. Do not attempt to use the new password until the cluster status is 'available'. Consider using AWS Secrets Manager with automatic rotation for Redshift to manage this lifecycle.

The most consequential API trap is assuming SCIM deprovisioning removes the database user. It does not. SCIM operates on the IAM Identity Center identity layer; the Redshift database user (IAMA:username or IAM:username) persists until explicitly dropped via SQL.

Without a reconciliation step - ideally automated via EventBridge + Lambda - deprovisioned IdP users remain as valid database principals indefinitely.

A second trap is the IAM: vs. IAMA: prefix split. GetClusterCredentials (with explicit DbUser) creates users prefixed IAM:; GetClusterCredentialsWithIAM (caller's IAM identity) creates users prefixed IAMA:.

SQL GRANTs and DROP USER statements must use the exact prefixed username. Mixing these in automation scripts produces silent permission failures or failed drops.

Rate limiting on Redshift API calls is enforced via AWS service quotas with no documented per-action thresholds and no rate-limit response headers. Clients must implement exponential backoff with jitter on ThrottlingException - AWS SDK default retry logic handles this if used, but raw HTTPS callers must implement it explicitly.

Pagination on DescribeClusters uses a Marker token with a hard maximum of 100 results per page; callers must loop until no NextMarker is returned.