---
title: Connectors | Developer Documentation
description: Configure connectors on self-hosted LlamaCloud, covering the encryption keys for stored credentials and OAuth tokens, which connection types to offer, and how to create and register your own Google Drive and SharePoint OAuth client apps.
---

## Self-Hosting Documentation Access

This section requires a password to access. Interested in self-hosting? [Contact sales](https://www.llamaindex.ai/contact) to learn more.

Password:

Access Documentation

Self-Hosting Documentation Access Granted Logout

Connectors sync files from Google Drive, SharePoint, S3, and Confluence into project folders. See [Connectors](/llamaparse/connectors/index.md) for how they work. On a self-hosted deployment you provide three things:

1. **Encryption keys.** LlamaCloud encrypts every credential it stores. Without a key, it refuses to store a credential and creating the connection fails.
2. **The connection types to offer.** For example, S3 only, or S3 plus Google Drive and SharePoint sign-in.
3. **OAuth client apps**, only if you offer the sign-in (“Sign in with Google” or “Sign in with Microsoft”) connections. You register these apps with Google or Microsoft yourself, then give LlamaCloud their client IDs and secrets through the API.

Connections that use keys (S3 access keys, a Google service account key, a SharePoint app registration, a Confluence API token) need only steps 1 and 2.

## Connector settings in values.yaml

Chart version 0.9.3 and later configures connectors under `config.connectors`. The chart passes these settings to every workload that stores or reads credentials: the API and the Temporal workers.

```
config:
  connectors:
    # Which connection types to offer (see below). This is the default.
    enabledAuthTypes: "google_drive:oauth,google_drive:service_account,sharepoint:oauth,sharepoint:service_account,s3:service_account"
    # Where Google or Microsoft sends users back after sign-in.
    # Defaults to https://<ingress.host>/credential-brokers/return.
    oauthReturnUrl: ""
    # Encrypt with AWS KMS...
    credentialsKmsKeyArn: ""
    tokenVaultKmsKeyArn: ""
    # ...or with master keys, and the sign-in seal key, from a Secret you create.
    secret: llamacloud-connector-secrets
```

Create the Secret before installing or upgrading. The chart never generates these keys:

Terminal window

```
kubectl create secret generic llamacloud-connector-secrets \
  --from-literal=CONNECTOR_AUTH_SEAL_KEY="$(openssl rand -base64 32)" \
  --from-literal=CONNECTOR_MASTER_KEY="$(openssl rand -base64 32)" \
  --from-literal=TOKEN_VAULT_MASTER_KEY="$(openssl rand -base64 32)"
```

Leave out `CONNECTOR_MASTER_KEY` or `TOKEN_VAULT_MASTER_KEY` when you set the matching KMS key ARN instead. The sections below explain each setting.

## Connector encryption keys

LlamaCloud keeps two kinds of connector secrets, and each kind is encrypted with its own key:

| Secret                                                    | Examples                                                                                      | KMS key                | Or master key in the Secret |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------- | --------------------------- |
| Credentials a connection holds itself                     | S3 access keys, Google service account keys, SharePoint client secrets, Confluence API tokens | `credentialsKmsKeyArn` | `CONNECTOR_MASTER_KEY`      |
| OAuth client apps and the tokens from sign-in connections | Your Google and Entra client secrets, users’ refresh tokens                                   | `tokenVaultKmsKeyArn`  | `TOKEN_VAULT_MASTER_KEY`    |

For each kind, set one of the two:

- **A KMS key**: the key ARN or alias ARN, including the region, for example `arn:aws:kms:us-east-1:123456789012:alias/llamacloud-connector-credentials`. The API and Temporal worker pods’ IAM role needs `kms:GenerateDataKey`, `kms:Decrypt`, and `kms:DescribeKey` on it. If both a KMS key and a master key are set, the KMS key is used.
- **A master key**: a random key in the Secret, for deployments without AWS KMS. Generate it with `openssl rand -base64 32`.

Rules for the keys:

- **Use a different key for each kind.** Don’t reuse `CONNECTOR_MASTER_KEY` as `TOKEN_VAULT_MASTER_KEY`, or one KMS key for both.
- **Never change or lose a key once connections exist.** Stored credentials can only be opened with the key that encrypted them. If a key changes, every connection that used it has to be deleted and made again.

Without a key, creating a key-based connection returns `503 Credentials could not be stored securely`, and registering an OAuth client app returns `500 Token vault encryption is not available`.

`CONNECTOR_AUTH_SEAL_KEY` is a third, separate key that protects the short-lived state passed back and forth during a sign-in. It must be 32 random bytes, base64-encoded (`openssl rand -base64 32`). Sign-in connections can’t be created without it. Key-based connections don’t need it.

## Choose which connection types to offer

`config.connectors.enabledAuthTypes` is a comma-separated list of `integration:auth_type` pairs. The API refuses any pair that isn’t listed with a `422`. Set it to `""` to turn connectors off.

| Pair                           | Connection                                                  | In the default |
| ------------------------------ | ----------------------------------------------------------- | -------------- |
| `s3:service_account`           | S3 with an access key pair                                  | Yes            |
| `google_drive:service_account` | Google Drive with a service account key file                | Yes            |
| `google_drive:oauth`           | Google Drive, sign in with Google                           | Yes            |
| `sharepoint:service_account`   | SharePoint with an Entra app registration and client secret | Yes            |
| `sharepoint:oauth`             | SharePoint, sign in with Microsoft                          | Yes            |
| `confluence:api_key`           | Confluence with an API token or personal access token       | No             |
| `confluence:oauth`             | Confluence Cloud, sign in with Atlassian                    | No             |

The cards in the **Add connection** dialog are fixed when the frontend image is built, and they match the default list. If you narrow the list, for example to `s3:service_account` only, the other cards still show but fail with a `422` when used. A connection type that isn’t in the default can’t be added from the dialog at all, though the API accepts it once you list it.

For an S3-only deployment, `s3:service_account` plus `CONNECTOR_MASTER_KEY` (or `credentialsKmsKeyArn`) is all you need. Skip the rest of this page.

## Enable sign-in connections

Sign-in connections run through your deployment’s own token vault, using the OAuth client apps you register below. Beyond the token vault key and `CONNECTOR_AUTH_SEAL_KEY`, they need a redirect URI:

```
https://<your-llamacloud-host>/credential-brokers/return
```

`<your-llamacloud-host>` is your `ingress.host`, the hostname you open the UI on. The chart builds this URL from `ingress.host` for you. Set `config.connectors.oauthReturnUrl` only if users reach LlamaCloud at a different URL, for example behind your own ingress.

The URI must match, character for character, what you register with Google and Microsoft below: same scheme, same host, no trailing slash. LlamaCloud sends it when the sign-in starts and again when it exchanges the code, and the provider rejects any mismatch.

## Create a Google OAuth client for Google Drive

Do this in a Google Cloud project your organization controls.

1. In the Google Cloud console, open **APIs & Services → Library** and enable the **Google Drive API** and the **Google Picker API**.

2. Open **Google Auth Platform → Branding** (the OAuth consent screen) and fill it in. Under **Audience**, pick:

   - **Internal** if only accounts in your Google Workspace will connect. This is the simplest choice, and Google doesn’t review Internal apps.
   - **External** if accounts from other domains must connect. `drive.readonly` is a restricted scope, so an External app needs Google’s verification before users outside your test users can use it.

3. Under **Data Access**, add these scopes:

   - `openid`
   - `.../auth/userinfo.email`
   - `.../auth/userinfo.profile`
   - `https://www.googleapis.com/auth/drive.readonly`

4. Under **Clients**, click **Create client**, choose **Web application**, and add one **Authorized redirect URI**: `https://<your-llamacloud-host>/credential-brokers/return`.

5. Copy the **Client ID** and **Client secret**.

LlamaCloud always asks for offline access, so each connection gets a refresh token and keeps syncing without the user signing in again.

## Create a Microsoft Entra app for SharePoint sign-in

This app is for the **SharePoint** (sign in with Microsoft) connection. It isn’t the same as the app registration a **SharePoint Keys** connection uses, which needs application permissions instead; see [SharePoint Connector](/llamaparse/connectors/sharepoint/index.md).

1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), go to **App registrations → New registration**.

2. Under **Supported account types**, choose **Accounts in any organizational directory (multitenant)**. LlamaCloud signs users in through Microsoft’s `organizations` endpoint, and a single-tenant app is rejected there.

3. Under **Redirect URI**, choose the **Web** platform and enter `https://<your-llamacloud-host>/credential-brokers/return`.

4. Under **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, add:

   - `openid`, `profile`, `email`, `offline_access`
   - `User.Read`
   - `Sites.Read.All`

5. So users can browse for a folder with Microsoft’s file picker, also add **SharePoint → Delegated permissions → `AllSites.Read`**. Without it the picker can’t open. Users can still create folders, but only by entering IDs.

6. Click **Grant admin consent** for your tenant. `Sites.Read.All` needs admin consent in most tenants, and this spares each user from asking for it.

7. Under **Certificates & secrets**, create a client secret. Copy its **Value**, not its **Secret ID**, and note its expiry date.

8. Copy the **Application (client) ID** from **Overview**.

These are all delegated permissions. The connection can read only what the signed-in user can open.

## Register OAuth client apps with the API

Give LlamaCloud each app’s client ID and secret with `POST /api/v2/internal/token-vault/apps`. The secret is encrypted with the token vault key and never returned. Each app applies at one level:

| `tenant_type`  | `tenant_id`         | Who can register it                                                            | Used for                        |
| -------------- | ------------------- | ------------------------------------------------------------------------------ | ------------------------------- |
| `global`       | omit                | A [global admin](/llamaparse/self_hosting/configuration/global-admin/index.md) | Every project in the deployment |
| `organization` | The organization ID | An organization admin                                                          | Projects in that organization   |
| `project`      | The project ID      | A project admin                                                                | That project only               |

On most deployments, one `global` app per provider is all you need. Call the API with the API key of an account that has the admin role for the level you register at:

Terminal window

```
LLAMACLOUD="https://llamacloud.example.com"


# Google Drive
curl -sS -X POST "$LLAMACLOUD/api/v2/internal/token-vault/apps" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "google_drive",
    "tenant_type": "global",
    "client_id": "'"$GOOGLE_CLIENT_ID"'",
    "client_secret": "'"$GOOGLE_CLIENT_SECRET"'"
  }'


# SharePoint (set expires_at to the client secret's expiry)
curl -sS -X POST "$LLAMACLOUD/api/v2/internal/token-vault/apps" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": "sharepoint",
    "tenant_type": "global",
    "client_id": "'"$ENTRA_CLIENT_ID"'",
    "client_secret": "'"$ENTRA_CLIENT_SECRET"'",
    "expires_at": "2027-09-30T00:00:00Z"
  }'
```

The response echoes the `client_id` and the app’s `id`, never the secret. The OAuth scopes are fixed for each integration, so you don’t send them.

`integration` accepts `google_drive`, `sharepoint`, and `confluence`. For Confluence, register an Atlassian OAuth 2.0 (3LO) app the same way, with the same redirect URI as its callback URL.

### Manage registered OAuth apps

| Request                                                                      | What it does                                                                                                                         |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /api/v2/internal/token-vault/apps?tenant_type=global`                   | List apps at a level (add `&tenant_id=…` for `organization` or `project`). Filter with `integration`, `is_enabled`, or `is_expired`. |
| `PATCH /api/v2/internal/token-vault/apps/{app_id}` with `{"enabled": false}` | Stop offering the app for new connections. Existing connections keep working.                                                        |
| `DELETE /api/v2/internal/token-vault/apps/{app_id}`                          | Delete the app. Returns `409` while any connection still uses it.                                                                    |

Apps can’t be edited. To rotate a client secret, register the new secret as a second app, disable the old one, and delete it once no connections use it. After its `expires_at`, an app is no longer offered for new connections.

## Troubleshooting self-hosted connectors

| Symptom                                                                           | What to check                                                                                                                                            |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `503 Credentials could not be stored securely` when adding a key-based connection | Neither `credentialsKmsKeyArn` nor `CONNECTOR_MASTER_KEY` in `config.connectors.secret` is set.                                                          |
| `500 Token vault encryption is not available` when registering an app             | Neither `tokenVaultKmsKeyArn` nor `TOKEN_VAULT_MASTER_KEY` in `config.connectors.secret` is set.                                                         |
| ”No enabled google\_drive app is configured for this tenant” at sign-in           | No app is registered for that integration at a level covering the project, or it’s disabled or past `expires_at`.                                        |
| Google: `redirect_uri_mismatch`; Microsoft: `AADSTS50011`                         | The redirect URI registered on the app doesn’t exactly match `https://<ingress.host>/credential-brokers/return` (or `config.connectors.oauthReturnUrl`). |
| Microsoft: `AADSTS50194`                                                          | The Entra app is single-tenant. Change **Supported account types** to multitenant.                                                                       |
| `422` naming an integration and auth type                                         | That pair isn’t in `config.connectors.enabledAuthTypes`.                                                                                                 |
| Syncs fail with decryption errors after a redeploy                                | A key in the Secret or a KMS key ARN changed. Restore the original.                                                                                      |