API Keys

The WarpStream API allows developers to manage API key permissions directly. This contrasts with the WarpStream console and the WarpStream Terraform provider, where API keys are always exposed as account keys, application keys or agent keys. For more information about this distinction, see Secrets Overview.

API requests to manage API keys must be authenticated with either an account key or an application key. Account keys can create, list, and delete account keys, as well as application keys in any workspace. Application keys can create, list, and delete application keys and agent keys, but only in their respective workspaces. See Workspaces and Access Controls.

API key permissions are represented as access grants. An application key is simply an API key with one set of grants, and an agent key is also just an API key with a different set of grants. Grants are specified when creating new API keys. For details, see the reference to create API keys.

Key formats

API keys are created in one of two formats.

• v1 key format: the secret starts with aks_. WarpStream stores the secret, so it can be read again later, for example with List.
• v2 key format: the secret starts with aks_v2_. WarpStream does not store the secret, only a hash of it. The secret is returned once, by the request that creates the key, and can’t be retrieved afterwards.

Keys in either format can be used wherever an API key is accepted, for example to authenticate API requests or Agents.

The v2 key format is created by the v2 create endpoints: Create API Key (v2), Create Virtual Cluster (v2) and Create Workspace (v2). Endpoints that return existing keys, such as List, Describe Virtual Cluster and List Virtual Clusters, return an empty key for keys in the v2 key format.

An existing key can’t be converted to the v2 key format. To move to it, create a new key with Create API Key (v2), switch your Agents or integrations to the new key, then delete the old one.