Connections

Manage connections to your data warehouses.

A connection stores the credentials CARTO uses to reach your data warehouse. Everything else — maps, workflows, tokens — is scoped to one.

Use these endpoints to provision connections programmatically: onboarding a new team, rotating credentials, or replicating a setup across organizations.

Endpoint

What it does

GET /v3/connections

List connections

POST /v3/connections

Create a connection

GET /v3/connections/{connectionId}

Get a connection

PATCH /v3/connections/{connectionId}

Update a connection

DELETE /v3/connections/{connectionId}

Delete a connection

These endpoints need an OAuth Access Token. See Authorization.

Credentials are write-only

Secrets you send are stored encrypted and are never returned by any endpoint. When updating a connection, omit them to keep the stored values.

Each provider takes a different config shape — BigQuery, Snowflake, Redshift, PostgreSQL, Databricks and Oracle. The request examples below cover the common authentication method for each.

Deleting a connection that is in use

Deleting a connection with maps or workflows behind it returns 409. Pass targetConnectionId to move them to another connection of the same provider first — it must belong to the same user and use the same provider.

privacy is private or shared. Sharing requires sharingScope — organization for everyone, or specific with the groupIds to share with.

Endpoints

List connections

get

/v3/connections

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

searchstringOptional

starredstring · enumOptionalPossible values:

order_bystringOptional

order_directionstring · enumOptionalPossible values:

Responses

200

The connections. Credentials are never returned.

application/json

A data warehouse connection. Credentials are never returned — secret fields are stripped from config.

idstring · uuidOptional

namestringOptional

provider_idstringOptional

user_idstringOptional

account_idstringOptional

privacystring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

Other propertiesanyOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

get/v3/connections

GET /v3/connections HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "provider_id": "text",
    "user_id": "text",
    "account_id": "text",
    "privacy": "private",
    "config": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "created_at": "2026-08-09T07:51:31.309Z",
    "updated_at": "2026-08-09T07:51:31.309Z",
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
]

Create a connection

post

/v3/connections

Creates a connection to a data warehouse.

The config object depends on provider_id and on the authentication method — see the examples below. Secrets you send here are stored encrypted and never returned by any endpoint.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Body

namestring · min: 1Required

provider_idstring · enumRequiredPossible values:

privacystring · enumOptionalPossible values:

groupIdsstring[]Optional

Required when privacy is shared.

Responses

200

The connection was created.

application/json

A data warehouse connection. Credentials are never returned — secret fields are stripped from config.

idstring · uuidOptional

namestringOptional

provider_idstringOptional

user_idstringOptional

account_idstringOptional

privacystring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

Other propertiesanyOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

post/v3/connections

POST /v3/connections HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 701

{
  "name": "example_bigquery_connection",
  "provider_id": "bigquery",
  "config": {
    "billing_project": "your-billing-project",
    "type": "service_account",
    "credentials": {
      "type": "service_account",
      "project_id": "your-project",
      "private_key_id": "ba0c1bdfcea5ca687ea2dfb136b6dd0b4c32a1c0",
      "private_key": "-----BEGIN PRIVATE KEY-----\\n...",
      "client_email": "user@your-project.iam.gserviceaccount.com",
      "client_id": "123456789",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/user%40your-project.iam.gserviceaccount.com"
    }
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "provider_id": "text",
  "user_id": "text",
  "account_id": "text",
  "privacy": "private",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-08-09T07:51:31.309Z",
  "updated_at": "2026-08-09T07:51:31.309Z",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get a connection

get

/v3/connections/{connectionId}

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionIdstring · uuidRequiredExample: 5a32a0ea-555a-48dd-aeb1-8768aae8ef1c

Responses

200

The connection.

application/json

A data warehouse connection. Credentials are never returned — secret fields are stripped from config.

idstring · uuidOptional

namestringOptional

provider_idstringOptional

user_idstringOptional

account_idstringOptional

privacystring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

Other propertiesanyOptional

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

get/v3/connections/{connectionId}

GET /v3/connections/{connectionId} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "provider_id": "text",
  "user_id": "text",
  "account_id": "text",
  "privacy": "private",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-08-09T07:51:31.309Z",
  "updated_at": "2026-08-09T07:51:31.309Z",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Update a connection

patch

/v3/connections/{connectionId}

Updates a connection. You can't change provider_id or the authentication method. Secrets can be omitted to keep the stored values.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionIdstring · uuidRequiredExample: 5a32a0ea-555a-48dd-aeb1-8768aae8ef1c

Body

privacystring · enumOptionalPossible values:

sharingScopestring · enumOptional

Required when privacy is shared, and must be omitted otherwise.

Possible values:

groupIdsstring[]Optional

Required when privacy is shared.

Other propertiesanyOptional

Responses

200

The updated connection.

application/json

A data warehouse connection. Credentials are never returned — secret fields are stripped from config.

idstring · uuidOptional

namestringOptional

provider_idstringOptional

user_idstringOptional

account_idstringOptional

privacystring · enumOptionalPossible values:

created_atstring · date-timeOptional

updated_atstring · date-timeOptional

Other propertiesanyOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

patch/v3/connections/{connectionId}

PATCH /v3/connections/{connectionId} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "privacy": "shared",
  "sharingScope": "organization",
  "groupIds": [
    "1"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "provider_id": "text",
  "user_id": "text",
  "account_id": "text",
  "privacy": "private",
  "config": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "created_at": "2026-08-09T07:51:31.309Z",
  "updated_at": "2026-08-09T07:51:31.309Z",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Delete a connection

delete

/v3/connections/{connectionId}

Deletes a connection. Pass targetConnectionId to move its maps and workflows to another connection of the same provider first.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionIdstring · uuidRequiredExample: 5a32a0ea-555a-48dd-aeb1-8768aae8ef1c

Body

targetConnectionIdstring · uuidOptional

Responses

204

The connection was deleted.

No content

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

409

The connection is in use by other users in your organization.

application/json

delete/v3/connections/{connectionId}

DELETE /v3/connections/{connectionId} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "targetConnectionId": "123e4567-e89b-12d3-a456-426614174000"
}

No content

PreviousResources API NextMaps and workflows

Last updated 8 days ago

Was this helpful?