> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/confluent-integration-setup.md).

# Confluent Integration Setup

#### Getting started

BalkanID connects to Confluent Cloud using a **Cloud API key** owned by a dedicated **service account**. We recommend a service account rather than a key owned by a person: a service account has no console login and no password, and its key keeps working when someone leaves the organization.

Before you begin, you must be an **OrganizationAdmin** in the Confluent Cloud organization you want to connect.

{% hint style="warning" %}
The key must be a **Cloud API key** (also shown as "Cloud resource management"), **not** a Kafka cluster API key. A cluster key only reaches a single cluster's data plane and cannot read users, service accounts, or role bindings at all — the integration will fail to authenticate.
{% endhint %}

#### Choose the role for the service account

The API key inherits the permissions of the service account that owns it, so that account's role determines what BalkanID can see.

| Capability                              | AccountAdmin | OrganizationAdmin |
| --------------------------------------- | ------------ | ----------------- |
| Users and organization                  | Yes          | Yes               |
| Service accounts                        | Yes          | Yes               |
| Environments and clusters               | Yes          | Yes               |
| Role bindings (entitlements and access) | Own only     | Yes               |
| API key inventory                       | No           | Yes               |
| SSO group mappings                      | No           | Yes               |
| Security insights                       | Partial      | Yes               |

**OrganizationAdmin is required for a complete access graph.** Confluent Cloud does not offer a read-only IAM role, so there is no lower-privilege option that can still read role bindings across the organization.

{% hint style="danger" %}
An under-privileged key does not produce an error — it produces an incomplete picture. Confluent returns an empty result rather than a permission failure, so an integration configured with an AccountAdmin key will report a successful sync while missing most entitlements and all credentials. If your first sync shows users but few or no entitlements, the key almost certainly lacks OrganizationAdmin.
{% endhint %}

{% hint style="info" %}
BalkanID only ever reads from Confluent Cloud. Every call the integration makes is an HTTP `GET`, and all activity by the service account appears in your Confluent Cloud audit log if you want to verify this independently.
{% endhint %}

#### Create a service account in Confluent Cloud

1. Sign in to [Confluent Cloud](https://confluent.cloud) as a user with the **OrganizationAdmin** role.
2. Open **Accounts & access** from the top-right menu, then select the **Service accounts** tab.

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FuEkoHh7TaCvekY8Tp273%2FScreenshot%202026-08-25%20at%205.57.16%E2%80%AFPM.png?alt=media&amp;token=ad58401f-8922-40ef-b4b7-58e3cbe7b6ab" alt="" width="176"><figcaption></figcaption></figure>

3. Click **Add service account**. Give it a name such as `balkanid-integration` and a description such as `BalkanID access extraction`, then click **Next**.

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FSRx5i7LUIed1wIAqPoCN%2FScreenshot%202026-08-18%20at%204.23.53%E2%80%AFPM.png?alt=media&amp;token=b75b89a3-fae7-408f-b806-fe84a3540bbe" alt=""><figcaption></figcaption></figure>

4. On the role assignment step, choose the **Organization** scope and grant the **OrganizationAdmin** role. Click **Next**, review, and click **Create**.

#### Create the Cloud API key

1. Open **API keys** from the menu panel on the right-hand side of the Confluent Cloud Console, then click **Add API key**.
2. For the account type, select **Service account** and choose the service account you created above.
3. For the resource scope, select **Cloud resource management**. Do not select a Kafka cluster.
4. Add a name such as `BalkanID` and click **Create API key**.
5. Copy both the **Key** and the **Secret**, or click **Download API key**.

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2Fn2XAme5vAaFy7I07ZGAH%2FScreenshot%202026-08-18%20at%204.29.00%E2%80%AFPM.png?alt=media&amp;token=3deb4ff5-2788-4a20-bc1a-8615b9ce9862" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The secret is displayed **only once**, at creation. If you lose it, you cannot retrieve it — you will need to delete the key and create a new one.
{% endhint %}

#### Configure Confluent with your BalkanID tenant

1. Log in to your BalkanID application.
2. Navigate to **Integrations** and click **Add Integration**.

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FCHJIRpH2vlYQLJUhMLeJ%2Fimage.png?alt=media&amp;token=70ddf205-c062-4aca-aa08-b0e677dcd735" alt="" width="563"><figcaption></figcaption></figure>

3. Select **Confluent** from the list of applications.
4. Assign a **primary owner** and, optionally, a **secondary owner** for the integration.
5. Under **Direct Configuration**, fill in:

| Field         | Value                                                                              |
| ------------- | ---------------------------------------------------------------------------------- |
| API Key       | The Cloud API key ID you copied above                                              |
| API Secret    | The secret shown at creation                                                       |
| Confluent URL | Leave blank unless instructed otherwise. Defaults to `https://api.confluent.cloud` |

6. Expand **Optional Configuration** if required, then save.

<figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FTx0c75pNi3oTxnY6KaSN%2Fimage.png?alt=media&amp;token=e94320eb-948f-4ed8-9edb-a79eeb70fdc6" alt="" width="563"><figcaption></figcaption></figure>

The integration is configured correctly when its status shows **Connected** and you see a **Data available** message after the first successful sync.

#### Integration Scopes

| **Read Only (Access Review) Scopes** | **Lifecycle Management Scopes** |
| ------------------------------------ | ------------------------------- |
| OrganizationAdmin (role)             | Not supported                   |


---

# 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.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/confluent-integration-setup.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.