> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/in-harness-3.0/connectors/configure.md).

# Connector Configuration Reference

This reference collects complete configuration examples for the most common connector types, in YAML, Terraform HCL, and REST API form. Use it when you define connectors as code rather than through the UI, or when you need to confirm the exact field names and secret reference syntax that Harness expects.

***

### Credential reference <a href="#credential-reference" id="credential-reference"></a>

Connectors reference secrets stored in [Harness Secret Manager](/harness-platform/3.0/harness-platform-resources/secrets/secrets-management/harness-secret-manager-overview.md) or an external vault. Secret references follow a scoped naming convention that determines where the secret is resolved from.

#### Secret reference format <a href="#secret-reference-format" id="secret-reference-format"></a>

| Format               | Scope                              | Example              |
| -------------------- | ---------------------------------- | -------------------- |
| `account.SecretName` | **Account**-level secret           | `account.github_pat` |
| `org.SecretName`     | **Organization**-level secret      | `org.aws_access_key` |
| `SecretName`         | **Project**-level secret (default) | `docker_password`    |

#### Authentication methods <a href="#authentication-methods" id="authentication-methods"></a>

The authentication method determines how credentials are presented to the external service.

| Method                    | Description                                                                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Username and token        | A username paired with a personal access token or password, stored as separate secrets.                                                                                      |
| SSH key                   | An SSH private key stored as a Harness SSH secret, used for Git SSH connections.                                                                                             |
| OAuth                     | An [OAuth 2.0](https://oauth.net/2/) flow that uses a configured OAuth app. The platform manages token refresh automatically.                                                |
| IAM role (AWS)            | Assume an Identity and Access Management (IAM) role using Security Token Service (STS). Requires a trust relationship with the Harness delegate or a cross-account role ARN. |
| Service account key (GCP) | A JSON key file for a GCP service account, stored as a Harness file secret.                                                                                                  |
| Inherit from delegate     | Use the credentials available on the delegate host, for example, an instance profile or workload identity.                                                                   |

#### Delegate selectors <a href="#delegate-selectors" id="delegate-selectors"></a>

Delegate selectors route connector operations to specific delegates. Use them when the target service is in a private network, or when only certain delegates have the required network access or credentials.

```yaml
connector:
  name: Private K8s Cluster
  identifier: k8s_private
  type: K8sCluster
  spec:
    credential:
      type: InheritFromDelegate
      spec:
        delegateSelectors:
          - private-network-delegate
          - us-east-1-delegate
```

***

### GitHub connector examples <a href="#github-connector-examples" id="github-connector-examples"></a>

The following examples show Git provider connector configuration for both HTTP and SSH connection types.

#### GitHub HTTP connector <a href="#github-http-connector" id="github-http-connector"></a>

```yaml
connector:
  name: GitHub HTTP
  identifier: github_http
  type: Github
  spec:
    url: https://github.com/my-org
    authentication:
      type: Http
      spec:
        type: UsernameToken
        spec:
          username: my-github-username
          tokenRef: account.github_pat
    apiAccess:
      type: Token
      spec:
        tokenRef: account.github_pat
    delegateSelectors: []
    executeOnDelegate: false
    type: Account
```

#### GitLab SSH connector <a href="#gitlab-ssh-connector" id="gitlab-ssh-connector"></a>

```yaml
connector:
  name: GitLab SSH
  identifier: gitlab_ssh
  type: Gitlab
  spec:
    url: git@gitlab.com:my-org
    authentication:
      type: Ssh
      spec:
        sshKeyRef: account.gitlab_ssh_key
    apiAccess:
      type: Token
      spec:
        tokenRef: account.gitlab_token
    delegateSelectors: []
    executeOnDelegate: true
    type: Account
```

The `type: Account` field at the end of the spec indicates that the URL points to the organization or account level, for example, `https://github.com/my-org`. Set this field to `Repo` when the URL points to a specific repository. Use account-level URLs where possible, because a single connector can then access all repositories in the organization.

***

### AWS connector example <a href="#aws-connector-example" id="aws-connector-example"></a>

AWS connectors support multiple credential types, including access keys, IAM roles, and delegate-inherited credentials. The following example uses IAM role-based authentication with cross-account access.

```yaml
connector:
  name: AWS Production
  identifier: aws_prod
  type: Aws
  spec:
    credential:
      type: ManualConfig
      spec:
        accessKey: <+secrets.getValue("account.aws_access_key")>
        secretKeyRef: account.aws_secret_key
      region: us-east-1
    crossAccountAccess:
      crossAccountRoleArn: arn:aws:iam::123456789012:role/HarnessCrossAccountRole
      externalId: harness-external-id
    delegateSelectors:
      - aws-delegate-us-east
```

#### AWS IAM role inherited from the delegate <a href="#aws-iam-role-inherited-from-the-delegate" id="aws-iam-role-inherited-from-the-delegate"></a>

```yaml
connector:
  name: AWS via Delegate
  identifier: aws_delegate
  type: Aws
  spec:
    credential:
      type: InheritFromDelegate
      spec:
        delegateSelectors:
          - aws-eks-delegate
    crossAccountAccess:
      crossAccountRoleArn: arn:aws:iam::987654321098:role/HarnessDeployRole
      externalId: harness-deploy-id
```

{% hint style="info" %}
**USE IAM ROLES OVER ACCESS KEYS**

When delegates run on AWS (EC2 or EKS), prefer the **Inherit from Delegate** credential type. This uses the instance profile or IAM Roles for Service Accounts (IRSA) attached to the delegate, which removes the need to store long-lived access keys as secrets.
{% endhint %}

***

### Kubernetes connector example <a href="#kubernetes-connector-example" id="kubernetes-connector-example"></a>

Kubernetes connectors provide access to clusters for deployment operations. The following example uses a service account token for authentication.

```yaml
connector:
  name: Production K8s
  identifier: k8s_prod
  type: K8sCluster
  spec:
    credential:
      type: ManualConfig
      spec:
        masterUrl: https://k8s-api.example.com:6443
        auth:
          type: ServiceAccountToken
          spec:
            serviceAccountTokenRef: account.k8s_sa_token
            caCertRef: account.k8s_ca_cert
    delegateSelectors:
      - k8s-delegate-prod
```

#### Kubernetes via delegate (in-cluster) <a href="#kubernetes-via-delegate-in-cluster" id="kubernetes-via-delegate-in-cluster"></a>

```yaml
connector:
  name: In-Cluster K8s
  identifier: k8s_in_cluster
  type: K8sCluster
  spec:
    credential:
      type: InheritFromDelegate
      spec:
        delegateSelectors:
          - in-cluster-delegate
```

When the [Harness Delegate](/harness-platform/3.0/harness-platform-resources/delegates/delegate-closed-beta/delegate-overview.md) runs inside the target Kubernetes cluster, use the **Inherit from Delegate** credential type. The delegate uses its own service account token and the in-cluster API endpoint, so no additional credentials are required. Confirm that the delegate's service account holds the [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) permissions required for deployment operations.

***

### HashiCorp Vault connector example <a href="#hashicorp-vault-connector-example" id="hashicorp-vault-connector-example"></a>

The Vault connector integrates with HashiCorp Vault for centralized secrets management. The following example configures Vault with token authentication and the [KV v2 secrets engine](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2).

```yaml
connector:
  name: HashiCorp Vault
  identifier: vault_prod
  type: Vault
  spec:
    authToken: account.vault_token
    basePath: /harness
    vaultUrl: https://vault.example.com:8200
    secretEngineManuallyConfigured: true
    secretEngineName: secret
    secretEngineVersion: 2
    renewalIntervalMinutes: 10
    secretId: null
    appRoleId: null
    isDefault: false
    isReadOnly: false
    delegateSelectors:
      - vault-delegate
```

#### Vault with AppRole authentication <a href="#vault-with-approle-authentication" id="vault-with-approle-authentication"></a>

```yaml
connector:
  name: Vault AppRole
  identifier: vault_approle
  type: Vault
  spec:
    appRoleId: my-approle-id
    secretId: account.vault_secret_id
    basePath: /harness
    vaultUrl: https://vault.example.com:8200
    secretEngineManuallyConfigured: true
    secretEngineName: secret
    secretEngineVersion: 2
    renewalIntervalMinutes: 10
    isDefault: true
    isReadOnly: false
```

For more information on generating the role ID and secret ID, see [AppRole authentication](https://developer.hashicorp.com/vault/docs/auth/approle).

{% hint style="warning" %}
When you use token authentication, confirm that the token has a sufficient time to live (TTL) and that `renewalIntervalMinutes` is set to a value lower than the token TTL. Harness renews the token automatically at this interval. If the token expires, all secrets stored in Vault become inaccessible until you configure a new token.
{% endhint %}

***

### Terraform provider <a href="#terraform-provider" id="terraform-provider"></a>

The [Harness Terraform provider](https://registry.terraform.io/providers/harness/harness/latest/docs) enables infrastructure-as-code management of connectors. The following examples create connectors using HCL.

```hcl
resource "harness_platform_connector_github" "example" {
  identifier  = "github_ci"
  name        = "GitHub CI"
  description = "GitHub connector for CI builds"
  org_id      = "default"
  project_id  = "my_project"
  url         = "https://github.com/my-org"
  connection_type = "Account"
  validation_repo = "my-repo"

  credentials {
    http {
      username  = "my-username"
      token_ref = "account.github_pat"
    }
  }

  api_authentication {
    token_ref = "account.github_pat"
  }
}
```

```hcl
resource "harness_platform_connector_aws" "example" {
  identifier  = "aws_prod"
  name        = "AWS Production"
  description = "AWS connector for production deployments"
  org_id      = "default"

  manual {
    access_key_ref = "account.aws_access_key"
    secret_key_ref = "account.aws_secret_key"
  }

  cross_account_access {
    role_arn    = "arn:aws:iam::123456789012:role/HarnessRole"
    external_id = "harness-external-id"
  }
}
```

***

### API reference <a href="#api-reference" id="api-reference"></a>

Manage connectors programmatically through the Harness REST API when you automate onboarding or synchronize connectors from an external system. The following endpoints are available for connector CRUD operations.

| Method   | Endpoint                                      | Description                                       |
| -------- | --------------------------------------------- | ------------------------------------------------- |
| `POST`   | `/v1/connectors`                              | Create a new connector.                           |
| `GET`    | `/v1/connectors`                              | List connectors with optional filters.            |
| `GET`    | `/v1/connectors/{identifier}`                 | Get a specific connector by identifier.           |
| `PUT`    | `/v1/connectors/{identifier}`                 | Update an existing connector.                     |
| `DELETE` | `/v1/connectors/{identifier}`                 | Delete a connector.                               |
| `POST`   | `/v1/connectors/test-connection/{identifier}` | Test the connectivity of an existing connector.   |
| `POST`   | `/v1/connectors/test-connection`              | Test a connector configuration without saving it. |

```bash
# Create a connector via API <a href="#create-a-connector-via-api" id="create-a-connector-via-api"></a>
curl -X POST 'https://app.harness.io/v1/connectors' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Harness-Account: YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "connector": {
      "name": "GitHub CI",
      "identifier": "github_ci",
      "type": "Github",
      "spec": {
        "url": "https://github.com/my-org",
        "type": "Account",
        "authentication": {
          "type": "Http",
          "spec": {
            "type": "UsernameToken",
            "spec": {
              "username": "my-username",
              "tokenRef": "account.github_pat"
            }
          }
        }
      }
    }
  }'
```

```bash
# Test an existing connector <a href="#test-an-existing-connector" id="test-an-existing-connector"></a>
curl -X POST 'https://app.harness.io/v1/connectors/test-connection/github_ci' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Harness-Account: YOUR_ACCOUNT_ID' \
  -H 'Content-Type: application/json'

# List all connectors with filters <a href="#list-all-connectors-with-filters" id="list-all-connectors-with-filters"></a>
curl -X GET 'https://app.harness.io/v1/connectors?type=Github&status=SUCCESS' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Harness-Account: YOUR_ACCOUNT_ID'
```

All API requests require an `x-api-key` header with a valid Harness API key and a `Harness-Account` header with your account identifier. For **Organization**-scoped or **Project**-scoped connectors, include the `org` and `project` query parameters.

***

### Related articles <a href="#related-articles" id="related-articles"></a>

* [Manage connectors](/harness-platform/3.0/in-harness-3.0/connectors/manage.md): To test, edit, and audit connectors in the Harness UI.
* [Connector troubleshooting](/harness-platform/3.0/in-harness-3.0/connectors/troubleshooting.md): To resolve authentication, network, and scope resolution failures.
* [Pipeline YAML v1 overview](https://github.com/iKettles/harness-gitbook/tree/main/3k-docs/platform/getting-started/pipeline/README.md): To reference a connector from a pipeline stage.