> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/configuration/security/configure-your-custom-service-account.md).

# Configure your custom service account

By default, each CARTO Self-Hosted installation includes a dedicated GCP service account key, provisioned by CARTO, that the platform uses to access certain CARTO-managed services. If you prefer to use **your own Google Cloud Platform (GCP) service account** instead, follow the steps below **before** installing.

{% hint style="info" %}
On Kubernetes you can avoid long-lived service account keys entirely by using keyless identity federation. See [Cloud Identities](/carto-self-hosted/configuration/security/cloud-identities.md): [Workload Identity in GCP](/carto-self-hosted/configuration/security/cloud-identities/use-workload-identity-in-gcp.md) and [EKS Pod Identity in AWS](/carto-self-hosted/configuration/security/cloud-identities/use-eks-pod-identity-in-aws.md).
{% endhint %}

## 1. Create and register the service account

1. **Create a dedicated GCP service account** for your CARTO Self-Hosted deployment in the GCP console.
2. **(Recommended for Single VM deployments)** Attach this service account to the Compute Engine instance running CARTO, so the platform authenticates via the instance's identity instead of a long-lived JSON key.
3. **Share the service account email with CARTO Support** (<support@carto.com>) so it can be granted the required permissions on CARTO infrastructure.

Wait for confirmation from CARTO Support before proceeding to step 2.

## 2. Configure the service account in your deployment

{% tabs %}
{% tab title="☸️ Kots (Admin Console)" %} <img src="/files/iX0yYSxrIcdJH0mbRf9w" alt="Kots" width="18">

1. Open the Admin Console:
   * **Single VM**: `http://<your-vm-ip>:30000`
   * **Standard Orchestrated**: `kubectl kots admin-console -n <namespace>`, then open `http://localhost:8800`
2. Go to **Config**.
3. Locate the **CARTO Platform credentials** field. This textarea contains the service account JSON key used by CARTO to access CARTO platform services. By default it holds the CARTO-provisioned service account.

{% hint style="warning" %}
Do not modify the **CARTO Platform credentials** field without guidance from CARTO Support. Contact <support@carto.com> before proceeding. They will confirm the service account has the correct permissions and walk you through the change.
{% endhint %}

4. Replace the existing JSON value with the JSON key of your custom service account.
5. Click **Save config**, then **Deploy** to apply the change.

{% hint style="info" %}
The **CARTO Platform credentials** field is only visible when Workload Identity is **disabled**. If you are using Workload Identity, the service account is configured in that section instead.
{% endhint %}
{% endtab %}

{% tab title="🛞 Helm (customizations.yaml)" %} <img src="/files/5mQydBQdQ20MZUxbcOKQ" alt="Helm" width="18">

Add the service account to your `customizations.yaml` using one of these two options:

**Option 1 — Inline value (create secret automatically):**

```yaml
cartoSecrets:
  defaultGoogleServiceAccount:
    value: |
      {
        "type": "service_account",
        "project_id": "<your_project_id>",
        "private_key_id": "<your_private_key_id>",
        "private_key": "-----BEGIN PRIVATE KEY-----\n<your_private_key>\n-----END PRIVATE KEY-----\n",
        "client_email": "<your_sa_email>@<your_project>.iam.gserviceaccount.com",
        "client_id": "<your_client_id>",
        "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/<your_sa_email>"
      }
```

**Option 2 — Existing Kubernetes secret:**

First, create the secret from your service account JSON key file:

```bash
kubectl create secret generic \
  mycarto-google-custom-service-account \
  --from-file=key=<PATH_TO_YOUR_SECRET.json> \
  -n <namespace>
```

Then reference it in your `customizations.yaml`:

```yaml
cartoSecrets:
  defaultGoogleServiceAccount:
    existingSecret:
      name: mycarto-google-custom-service-account
      key: key
```

Once your `customizations.yaml` is updated, apply with:

```bash
helm upgrade carto carto/carto \
  --namespace <namespace> \
  -f carto-values.yaml \
  -f carto-secrets.yaml \
  -f customizations.yaml
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-self-hosted/configuration/security/configure-your-custom-service-account.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.