> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use API Keys to Authenticate to StreamNative Cloud

<Note title="Note">
  You need to upgrade the Pulsar cluster to the following minimum versions (`2.9.5.2`, `2.10.4.4`, or `3.0.0.3`) in order to access this feature. If you want to turn this feature on, please [submit a ticket](https://support.streamnative.io/hc/en-us/requests/new) to the support team.
</Note>

StreamNative Cloud API keys are used to control access to StreamNative Cloud components and resources.

API keys are JSON Web Tokens (JWTs) issued and managed in StreamNative Cloud. They allow you to create long-lived tokens and revoke them. These API keys are associated with the service accounts and the organization from which you create them. For details about using user and service accounts and their ownership of API keys, see [Ownership of API keys](#ownership-of-api-keys).

Use the [API keys](#cluster-api-keys) to control access to StreamNative Cloud clusters. Each API key is scoped for an entire organization.

## API Key v1 vs API Key v2

API Key v2 introduces organization-level authentication to simplify credential management and expand API key usage beyond Pulsar clusters to StreamNative Cloud APIs.

### Comparison

| Feature                                 | API Key v1                              | API Key v2                                         |
| --------------------------------------- | --------------------------------------- | -------------------------------------------------- |
| Scope                                   | Instance-level                          | Organization-level                                 |
| Key management                          | Separate API keys required per instance | Single API key can be used across the organization |
| Authorization model                     | Instance-scoped permissions             | Role-based access control (RBAC)                   |
| Pulsar cluster authentication           | Supported                               | Supported                                          |
| StreamNative Cloud API authentication   | Not supported (OAuth required)          | Supported                                          |
| CLI and Terraform support for Cloud API | Not supported                           | Planned in upcoming release                        |

### Key improvements in API Key v2

* **Organization-level scope** – Manage authentication at the organization level instead of per instance
* **Simplified access management** – No need to create or manage instance-specific API keys
* **RBAC-based authorization** – Fine-grained permissions without requiring multiple keys
* **Expanded authentication coverage** – API keys can be used for both Pulsar clusters and StreamNative Cloud APIs
* **Future extensibility** – Enables upcoming platform security and automation capabilities

> **Important**
> API Key v2 keys cannot be used with Pulsar clusters that have not been upgraded to support API Key v2.

> **Migration considerations**
>
> * Existing API Key v1 credentials will always continue to work even after the migration.
> * Organizations must be upgraded to API Key v2 before new v2 keys can be used.
> * Existing clusters may require upgrades to fully support API Key v2 authentication.

> **Note**
> Support for API key authentication to StreamNative Cloud APIs via **snctl** and the **Terraform provider** will be available in a future release.

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

* [StreamNative Cloud Console](https://console.streamnative.cloud)

For recommendations on using API keys, see [Best Practices for Using API Keys in StreamNative Cloud](/cloud/security/authentication/service-accounts/use-api-keys/api-keys-best-practices).

## Ownership of API keys

Each API key is associated with a specific \[service account]\[id:service-accounts].

* A best practice is to create separate service accounts associated with an API keys for each applications or use case.

* Using API keys associated with a user account is currently not supported yet.

* API keys are immutable and cannot be modified. If you need to change the permissions associated with an API key, you must delete the key and create a new one.

* Access control lists (ACLs) and role bindings are associated with **principals**, not with API keys. For details, see [Authorization and ACLs](/cloud/security/access/access-control-lists/authorization-and-acls).

* Restric access to an application that uses an API key associated with a service account:
  * For resource API keys, you can use [access control lists (ACLs)](/cloud/security/access/access-control-lists/authorization-and-acls).

<Warning title="Warning">
  When you delete a service account, all associated API keys will also be deleted. Any client applications using a deleted API key will lose access, which many cause an outage for your streaming application. Always confirm that none of the API keys owned by an account are in active use before deleting a service account.
</Warning>

## API keys

API Keys are used to control access to specific StreamNative Cloud clusters. Each Cluster API key is valid for one specific Organization. You can view the API keys of your organization by going to the Service Accounts page, and clicking on a Service Account's name, or by using `snctl get apikey -O your-org-name`.

<Note title="Important">
  API keys propagate quickly after creation, usually within a few minutes. If you try to use an API key before propagation completes, authentication failures occur. Depending on workloads, you might need to wait a few minutes more and try again.
</Note>

### Prerequisites

Ensure your Pulsar cluster has been upgraded to the following minimum versions:

* 2.9.5.2
* 2.10.4.4
* 3.0.0.3

To use snctl for managing API keys, you will need snctl version 0.16.0 or later.

### Create an API key

<span id="create-api-key" />

<Tabs>
  <Tab title="StreamNative Console">
    To create an API key for a specific service account in StreamNative Cloud Console, follow these steps.

    1. On the left navigation pane, click **Service Accounts**.

    2. On the Service Accounts page, select a specific service account.

    <Note title="Tip">
      You can also click **New** on the top-right corner and select **Create API Key** to create the API key for any service account.
    </Note>

    3. On the API Key page of this service account, click **New API Key**.

    4. Specify the required attributes for the API key.
       | Field                  | Description                                                                                                        |
       | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
       | Name                   | The name of the API key.                                                                                           |
       | Expiration date        | By default, each API key expires in 30 days. If you want it to be long-lived, you can select `No expiration date`. |
       | Service Account        | The service account you want to associate the API key with. The one selected in step 2 is auto-populated.          |
       | Description (optional) | The descriptive text to introduce the API key.                                                                     |

    5. Click **Confirm**.

    6. Click **Copy and close** to copy the generated API key and save it in a safe location for future use.

    <Warning title="Warning">
      Make sure the generated API key is securely saved since you won't be able to see it again after closing this window.
    </Warning>
  </Tab>

  <Tab title="snctl">
    To create an API key using snctl, use the `snctl create apikey` command:

    ```bash theme={null}
    snctl create apikey APIKEY_NAME --service-account-name SERVICE_ACCOUNT_NAME --expiration-time EXPIRE_TIME --description DESCRIPTION
    ```

    \| Flags | Description |
    \|--description | The description of API Key |
    \|--expiration-time | The expiration time of an API Key, the value is time in days to expire to with --expiration-time (or minutes, hours, days e.g.: 10m, 3h, 2d) or a time value with format like '2006-01-02T15:04:05Z'or 0 means never expire. |
    \|--service-account-name | The service account name of API key. |

    ## Examples

    To create an API key that never expires, do the following:

    ```bash theme={null}
    snctl create apikey test-apikey --service-account-name test-api-key --expiration-time 0 --description 'this is test' -O sndev
    ```

    To create an API key that expires in 30 days, do the following:

    ```bash theme={null}
    snctl create apikey test-apikey2 --service-account-name test-api-key --expiration-time 30d --description 'this is test' -O sndev
    ```

    To create an API key that expires in at a specific time, use the following:

    ```bash theme={null}
    snctl create apikey my-api-key --service-account-name my-service-account --expiration-time "2025-02-08T15:38:40Z" --description 'API Key for development team' -O my-organization
    ```
  </Tab>

  <Tab title="terraform">
    To create an API key using the StreamNative Terraform module, refer to the [Terraform documentation](https://registry.terraform.io/providers/streamnative/streamnative/latest/docs/resources/apikey).
  </Tab>
</Tabs>

## Using API keys to connect to your cluster

After creating an API key in StreamNative Cloud Console, you can use it to authenticate Kafka, Pulsar, and MQTT clients.

### Kafka Clients

<span id="kafka-clients" />

You can use API keys with [SASL/PLAIN authentication](https://kafka.apache.org/documentation/#security_sasl_plain) to connect Kafka clients to StreamNative Cloud clusters.

To configure SASL authentication on the clients:

1. Configure the JAAS configuration property for each client in `producer.properties` or `consumer.properties`. The login module describes how the clients like producers and consumers can connect to the cluster. Below is an example configuration for a client for the **PLAIN** mechanism:

   ```yaml theme={null}
   sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
   username="<tenant>/<namespace>" \
   password="token:<API KEY>";
   ```

   Use `<tenant>/<namespace>` as `username` and `<API KEY>` in `password`.

2. Configure the following properties in `producer.properties` or `consumer.properties`:
   ```yaml theme={null}
   security.protocol=SASL_SSL
   sasl.mechanism=PLAIN
   ```

For configuring Kafka clients in different languages to use API keys, you can find examples on ["Build Applications > Kafka Clients"](/cloud/build/kafka-clients/kafka-on-cloud#kafka-clients).

### Pulsar Clients

<span id="pulsar-clients" />

You can use API keys with [JWT authentication](https://pulsar.apache.org/docs/security-jwt/) to connect Pulsar clients to StreamNative Cloud clusters.

For configuring Pulsar clients in different languages to use API keys, you can find examples on ["Build Applications > Pulsar Clients"](/cloud/build/pulsar-clients/qs-connect).

For more examples of configuring Pulsar clients using API keys, see [JWT Authentication](https://pulsar.apache.org/docs/security-jwt/#configure-jwt-authentication-in-pulsar-clients) in Pulsar documentation.

### MQTT Clients

You can use API keys as `password` to connect MQTT clients to StreamNative Cloud clusters.

An example is shown below, where `<username>` can be any string and `password` is the API key.

```java theme={null}
Mqtt5SimpleAuth simpleAuth = Mqtt5SimpleAuth.builder().username("<username>")
                .password("<API KEY>")
                .build();
```

## Deleting and Revoking API Keys

<Tabs>
  <Tab title="StreamNative Console">
    To delete or revoke an API key for a specific service account in StreamNative Cloud Console, follow these steps.

    1. On the left navigation pane, click **Service Accounts**.

    2. On the Service Accounts page, select a specific service account.

    3. On the API Key page of this service account, click the Ellipsis (...) icon in the row of the API key that you want to revoke/delete, and select **Revoke** or **Delete**.

    4. Type the API key’s name to confirm and then click **Revoke** or **Confirm**.
  </Tab>

  <Tab title="snctl">
    To revoke an API key for a specific service account using snctl, use `snctl revoke apikey`.

    ```bash theme={null}
    snctl revoke apikey name-of-apikey -O your-org-name
    ```

    To delete an API key using snctl, use this `snctl delete apikey`:

    ```bash theme={null}
    snctl delete apikey test-apikey-name -O your-org-name
    ```
  </Tab>

  <Tab title="terraform">
    To delete or revoke an API key using the StreamNative Terraform module, refer to the [Terraform documentation](https://registry.terraform.io/providers/streamnative/streamnative/latest/docs/resources/apikey).
  </Tab>
</Tabs>

<Note title="What's expected after a revocation?">
  * Revoked API keys will be removed from their service accounts in 15 days.
  * If an API key gets revoked when being used by Kafka clients, the connection will stay alive. For Pulsar clients, the connection will be terminated in 1 minute.
</Note>

<Note title="What's expected after a deletion?">
  If an API key is deleted, it will simultaneously be revoked.
</Note>

## Cloud API keys

StreamNative Cloud doesn't support using API keys to access StreamNative Cloud API. Instead, you can use [OAuth2](/cloud/security/authentication/service-accounts/use-oauth/access-cloud-api-oauth) to connect to the StreamNative Cloud API.