Skip to main content
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 to the support team.
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. Use the 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

FeatureAPI Key v1API Key v2
ScopeInstance-levelOrganization-level
Key managementSeparate API keys required per instanceSingle API key can be used across the organization
Authorization modelInstance-scoped permissionsRole-based access control (RBAC)
Pulsar cluster authenticationSupportedSupported
StreamNative Cloud API authenticationNot supported (OAuth required)Supported
CLI and Terraform support for Cloud APINot supportedPlanned 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: For recommendations on using API keys, see Best Practices for Using API Keys in StreamNative Cloud.

​
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.
  • Restric access to an application that uses an API key associated with a service account:
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.

​
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.
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.

​
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

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.
You can also click New on the top-right corner and select Create API Key to create the API key for any service account.
  1. On the API Key page of this service account, click New API Key.
  2. Specify the required attributes for the API key.
    FieldDescription
    NameThe name of the API key.
    Expiration dateBy default, each API key expires in 30 days. If you want it to be long-lived, you can select No expiration date.
    Service AccountThe 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.
  3. Click Confirm.
  4. Click Copy and close to copy the generated API key and save it in a safe location for future use.
Make sure the generated API key is securely saved since you won’t be able to see it again after closing this window.

​
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

You can use API keys with SASL/PLAIN authentication 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: 
    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: 
    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”.

​
Pulsar Clients

You can use API keys with JWT authentication 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”. For more examples of configuring Pulsar clients using API keys, see JWT Authentication 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. 
Mqtt5SimpleAuth simpleAuth = Mqtt5SimpleAuth.builder().username("<username>")
                .password("<API KEY>")
                .build();

​
Deleting and Revoking API Keys

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.
  • 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.
If an API key is deleted, it will simultaneously be revoked.

​
Cloud API keys

StreamNative Cloud doesn’t support using API keys to access StreamNative Cloud API. Instead, you can use OAuth2 to connect to the StreamNative Cloud API.