<a id="cloud-api-key-resource"></a>

<a id="cloud-api-keys"></a>

<a id="api-keys-overview"></a>

# Use API Keys to Authenticate to Confluent Cloud

You can use Confluent Cloud API keys to authenticate to Confluent Cloud components and
resources. Each API key is associated with a specific [user account](../../../../../_glossary.md#term-user-account)
or [service account](../../../../../_glossary.md#term-service-account) and can be scoped for use with specific Confluent Cloud
resources.

<!-- WARNING: THIS IS A SHARED FILE AND THE SOURCE IS LOCATED IN DOCS-COMMON. DO NOT ADD TO ANY OTHER REPO. -->

Each Confluent Cloud API key consists of an API key ID and an API secret that are used to
uniquely identify and authenticate an application when you use the Confluent CLI
or the Confluent Cloud APIs.

API keys are long-lived, static credentials that provide direct authentication without
token exchange. Once created, they remain valid until rotated or deleted.

<a id="api-key-format"></a>

## API key format

#### NOTE
Starting July 30, 2025, API secrets include a `cflt` prefix. The prefix appears
only in API secrets (not API key IDs) and helps secret scanning tools detect and
flag accidentally leaked Confluent secrets in code, logs, and configuration files.
API secrets created before this date may not include `cflt`; both old and new
formats continue to work for authentication.

### API key ID format

The API key ID is a unique identifier for the API key. It is used as the username
in client configurations and is not considered secret information.

Example:

```text
ABCD1234567890AB
```

### API secret format

The API secret is the confidential credential used with the API key ID to authenticate.
The secret is shown only once at creation and cannot be retrieved later.

API secrets created after July 30, 2025 have a `cflt` prefix followed by 60
characters consisting of `A-Z`, `a-z`, `0-9`, `+` or `/`. For example:

```text
cfltT8d8RzkNseTMEDKcjNM1BZTFPHqRn/dQm9q7w6SjzZ12wZfwjaJdipHZtDjw
```

Additionally, the final 6 characters contain a Base64-encoded CRC32 checksum of the
prior 54 characters, which helps virtually eliminate false positives during offline
secret scanning.

#### Secret detection

The structured format with checksum validation enables reliable detection of API secrets
in code repositories, logs, and configuration files. A Python snippet to validate a
probable API secret is shown below:

```python
import base64
import re
import zlib

PATTERN = re.compile(r"cflt([A-Za-z0-9+/]{54})([A-Za-z0-9+/]{6})")
INPUT = "cfltT8d8RzkNseTMEDKcjNM1BZTFPHqRn/dQm9q7w6SjzZ12wZfwjaJdipHZtDjw"

for match in PATTERN.finditer(INPUT):
    checksum = zlib.crc32(match.group(1).encode("ascii"))
    expected = base64.b64encode(checksum.to_bytes(4, "little"))[:6]
    if match.group(2) == expected.decode("ascii"):
        print(f"Potential Confluent API Secret: {match.group(0)}")
```

#### Notes

- Do not infer scope or permissions from the format of the key or secret. Use the
  Confluent Cloud Console, Confluent CLI, or Confluent Cloud APIs to determine scope and permissions.
- Store the API secret securely (for example, a secrets manager). If the secret is
  lost, rotate or create a new key to obtain a new secret.
- API key operations (`CreateAPIKey`, `DeleteAPIKey`, `UpdateAPIKey`, `GetAPIKey`,
  `GetAPIKeys`) and authentication events (`kafka.Authentication`) are captured in
  audit logs for security monitoring and compliance. For audit event details, see
  [API key management events](../../../../../monitoring/audit-logging/event-methods/organization-events.md#organization-api-key) and
  [API key authentication events](../../../../../monitoring/audit-logging/event-methods/authorization-authentication-events.md#kafka-authentication-examples).

<a id="cloud-api-key-resource-scopes"></a>

## Resource scopes

Confluent Cloud API keys can be created for the following resource scopes:

Kafka cluster
: Used to access the specified Kafka cluster. To create an API key for
  Kafka, you must specify the Environment and Kafka cluster.

Schema Registry
: Used to access the specified Schema Registry. To create an API key for
  Schema Registry, you must specify the Environment and Schema Registry cluster.

ksqlDB cluster
: Used to access the specified ksqlDB application. To create an API
  key for ksqlDB, you must specify the Environment and ksqlDB cluster.

Flink region
: Used to access the Flink compute pools and statements in the
  specified region. To create an API key for Flink, you must specify
  the Environment, cloud service provider, and region.

Tableflow
: Used to authenticate to [Catalog APIs](https://docs.confluent.io/cloud/current/ccloud/catalog-integrations-tableflow-v-1/)
  The API key is scoped to any topics the principal has access to, which
  can span across multiple Confluent Cloud environments and clusters.

Cloud resource management
: Used to access the resource management APIs for managing the Confluent Cloud
  resources in your organization. For details, see [Confluent Cloud APIs](../../../../../api.md#cloud-apis).

Global
: Used to access all Confluent Cloud resources, with some limitations (see [Known limitations](#global-api-key-limitations)). This key is limited to the organization in which it was created.

To create and manage Confluent Cloud API keys, you can use the following tools:

* [Confluent Cloud Console](https://confluent.cloud)
* [Confluent CLI](https://docs.confluent.io/confluent-cli/current/overview.html)
* [REST API](https://docs.confluent.io/cloud/current/api.html#tag/API-Keys-(iamv2))
* [Terraform](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_api_key)

For recommendations on using API keys, see [Best Practices for Using API Keys on Confluent Cloud](best-practices-api-keys.md#api-keys-best-practices).

<a id="cloud-api-key-ownership"></a>

## API keys and Confluent Cloud accounts

Each API key is associated with a specific [user account](../../../user-identities/user-accounts/overview.md#user-accounts) or
[service account](../overview.md#service-accounts). The limit on the number of API keys
that can be associated with user or service accounts is specified in the
[service quotas for API keys](../../../../../quotas/service-quotas.md#service-quotas-api-keys).

* A best practice is to create separate service accounts associated with an
  API key for each application or use case to narrow the operational impact of
  retiring a specific API key.
* Because a user’s access to a resource might change over time, you should avoid
  using API keys associated with user accounts for production environments. You
  can use these API keys for development and testing. When an API key is tied
  to a user account, it inherits the permissions of that account. Consequently, if
  the user account is deleted, the associated API key will also be deleted,
  potentially causing unexpected disruptions.
* Permissions are not associated with an API key, but with the user or service account.
  For details, see [Role-based Access Control (RBAC) on Confluent Cloud](../../../../access-control/rbac/overview.md#cloud-rbac) and [ACL Overview](../../../../access-control/acls/overview.md#acl-manage).
* Group mapping permissions are not granted to an API key associated with an
  SSO user account. For details, see [Limitations](../../../user-identities/user-idps/sso/group-mapping/overview.md#group-mapping-limitations).

#### WARNING
Before deleting a user or service account, verify that any associated API
keys are not in active use. To view the API keys associated with a user or
service account, see [View API keys](manage-api-keys.md#view-api-keys).

When you delete a user account or service account, all access by that account
is revoked, including access using any associated API keys.

<a id="cloud-global-api-keys"></a>

## Global API keys

Global API keys simplify authentication across these Confluent Cloud resources:

* Cloud Management API
* Kafka clusters
  \* [Enterprise](../../../../../clusters/cluster-types.md#enterprise-cluster) and [Freight](../../../../../clusters/cluster-types.md#freight-cluster) (currently private only)
  \* [Dedicated](../../../../../clusters/cluster-types.md#dedicated-cluster) clusters (public and private)
* Schema Registry (private networking)
* Tableflow
* Flink
* ksqlDB

With global API keys, you can streamline your development workflow whether you’re building new applications,
managing infrastructure with Terraform, or implementing multi-cluster failover scenarios.

#### NOTE
A global API key can be used across Confluent Cloud services, but it does not grant any
permissions by itself. Whether the key is authorized to perform a given operation
depends entirely on the [RBAC roles](../../../../access-control/rbac/overview.md#cloud-rbac) and
[ACLs](../../../../access-control/acls/overview.md#acl-manage) assigned to the principal (user account or service account)
that owns the key. Before using a global API key, ensure the owning principal has
the appropriate permissions for each resource it needs to access.

To reduce the scope of a global API key, create separate service accounts with
only the permissions required for each use case, and create a global API key for
each service account. For details, see [Service Accounts on Confluent Cloud](../overview.md#service-accounts).

Each user account or service account can create only two global API keys. When only accessing a specific Confluent resource, use resource-scoped keys.

#### IMPORTANT
**Global API keys count against the** Kafka **API key quota of every supported cluster.**

When a global API key is created, it counts toward the per-cluster Kafka API key
quota for every supported cluster in the organization, not just the clusters it
is actively used with. A single global API key is counted once against each
[Dedicated](../../../../../clusters/cluster-types.md#dedicated-cluster), [Enterprise](../../../../../clusters/cluster-types.md#enterprise-cluster),
and [Freight](../../../../../clusters/cluster-types.md#freight-cluster) cluster’s limit. Plan accordingly before
creating global API keys in organizations with many supported clusters. For
quota details, see [API keys](../../../../../quotas/service-quotas.md#service-quotas-api-keys).

To create a global API key, use the Confluent Cloud API with the resource defined as `global`.
Replace `<service-account-id>` with the ID of the service account to own the key (for example, `sa-123456`).

**Using a Bearer token:**

```bash
curl -X POST "https://api.confluent.cloud/iam/v2/api-keys" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "spec": {
      "display_name": "my-global-key",
      "description": "Global API key for multi-service access",
      "owner": {"id": "<service-account-id>"},
      "resource": {"id": "global"}
    }
  }'
```

**Using Basic auth with a Cloud API key:**

Replace `<cloud-api-key>` and `<cloud-api-secret>` with your Cloud API key credentials.

```bash
curl --request POST \
  --url 'https://api.confluent.cloud/iam/v2/api-keys' \
  --header "Authorization: Basic $(echo -n '<cloud-api-key>:<cloud-api-secret>' | base64)" \
  --header 'Content-Type: application/json' \
  --data '{
    "spec": {
      "display_name": "my-global-key",
      "description": "Global API key for multi-service access",
      "owner": {"id": "<service-account-id>"},
      "resource": {"id": "global"}
    }
  }'
```

<a id="choosing-api-key-type"></a>

## Choosing an API key type

Use the following guidance to decide which API key type fits your use case.

**Use a global API key when:**

* Your application accesses more than one Confluent Cloud resource type. For example,
  a service that reads from Kafka and queries Flink, or writes to Kafka and
  validates schemas against Schema Registry.
* You are managing infrastructure with Terraform and want a single credential
  to configure the `confluent` provider across all resource types.
* You are implementing multi-cluster failover and need the same key to work
  across multiple Kafka clusters without reconfiguration.
* You are an admin running organization-wide workflows (for example, provisioning
  environments, clusters, and ACLs) and want to avoid juggling separate Cloud
  management and data-plane keys.
* You are getting started with Confluent Cloud development and want to minimize the
  number of credentials to manage.

Global API keys are not intended to replace your existing resource-scoped API keys.
Each user account and service account is limited to two global API keys, and there
are known limitations on which Confluent Cloud resources they support. Review the
[known limitations](#global-api-key-limitations) and
[service quotas](../../../../../quotas/service-quotas.md#service-quotas-api-keys) before deciding whether global API
keys are preferable to Cloud or resource-scoped API keys for your use case.

**Use a Cloud resource management key when:**

* Your application only calls the Confluent Cloud management APIs (for example,
  creating clusters, managing service accounts, or reading billing data) and
  does not need direct access to any Kafka, Schema Registry, Flink, or ksqlDB data planes.
* You need strict isolation between control-plane and data-plane credentials.

**Use a resource-scoped** Kafka **key when:**

* Your application connects to a single Kafka cluster and has no need to access
  other Confluent Cloud resource types.
* Your cluster is a [Basic](../../../../../clusters/cluster-types.md#basic-cluster) or [Standard](../../../../../clusters/cluster-types.md#standard-cluster) cluster, which do not support global API keys.
* You require fine-grained key isolation. For example, separate credentials
  per cluster for compliance or security reasons.

<a id="global-api-key-limitations"></a>

### Known limitations

* Global API keys do not support [Basic](../../../../../clusters/cluster-types.md#basic-cluster) and [Standard](../../../../../clusters/cluster-types.md#standard-cluster) Kafka clusters or
  public-networking Schema Registry clusters at this time. Use resource-scoped keys for those resources.
  For the full list of supported resources, see [Global API keys](#cloud-global-api-keys).
* You cannot convert an existing resource-scoped API key into a global API key.
* Each user account or service account is limited to two global API keys.
* Global API keys do not provide access to [Confluent Cloud audit logs](../../../../../monitoring/audit-logging/cloud-audit-log-concepts.md#cloud-audit-logs).
  Consuming audit logs requires a dedicated API key scoped to the audit log cluster.
  For details, see [Consume with Confluent CLI](../../../../../monitoring/audit-logging/configure.md#cloud-audit-logs-consume-cli).
* When a global API key is created, it counts toward the per-cluster Kafka API key quota
  for every supported cluster in the organization, not just the clusters it is actively
  used with. A single global API key is counted once against each [Dedicated](../../../../../clusters/cluster-types.md#dedicated-cluster), [Enterprise](../../../../../clusters/cluster-types.md#enterprise-cluster),
  and [Freight](../../../../../clusters/cluster-types.md#freight-cluster) cluster’s limit. For quota details, see [API keys](../../../../../quotas/service-quotas.md#service-quotas-api-keys).