Create

Create a new API Key.

API key names may only contain underscores and alphanumeric characters. WarpStream will assign the provided name to the new key after adding an akn_ prefix.

Create requests must provide a list of access grants to associate with the new key. For simplicity we recommend assigning each key a single access grant.

Note that if the API key you create is associated with WarpStream's BYOC Schema Registry, you need to set virtual_cluster_type to byoc_schema_registry. See example below.

An access grant is an object with four fields: workspace_id, principal_kind, resource_kind, and resource_id. They are subject to the following restrictions.

• workspace_id specifies which workspace the new API key should be authorized to access, in other words which workspace it belongs to. It should be specified when the request to create a new API key is authenticated with an account key since the new key's workspace is otherwise undetermined. It should be omitted when creating an API key using an application key. Any API key created programmatically with an application key will be assigned to the same workspace that the application key belongs to.
• principal_kind may be app, app_r, agent, or agent_r. app and app_r correspond to application keys and read-only application keys, while agent and agent_r correspond to agent keys and read-only agent keys.
• resource_kind may be *, virtual_cluster, virtual_cluster_topics, virtual_cluster_credentials, or virtual_cluster_acls.

  • * grants access to every resource in the workspace and is only supported for grants with principal kind app or app_r.
  • virtual_cluster is only supported for grants with principal kind agent or agent_r.
  • virtual_cluster_topics, virtual_cluster_credentials, and virtual_cluster_acls scope an application key to a single resource kind on a single virtual cluster. They are only supported for grants with principal kind app. See example below.
• resource_id: may be * or one of your virtual cluster IDs. Agent keys may be granted access to a single virtual cluster via its ID, or to all virtual clusters in your account by setting this field to *. Grants whose resource_kind is virtual_cluster_topics, virtual_cluster_credentials, or virtual_cluster_acls must name a specific virtual cluster ID. * is rejected for those resource kinds.

Request

curl https://api.warpstream.com/api/v1/create_api_key \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{"name":"example_agent_key", "access_grants": [
    {"principal_kind": "agent", "resource_kind": "virtual_cluster", "resource_id": "vci_1d4930d7_8e6d_4ad9_b27a_654ed4aaa3ee"}
]}'

Response

{
  "id": "aki_007f0341_3ab3_457a_a513_2b2c9415582f",
  "name": "akn_example_agent_key",
  "key": "aks_a51b1fb20ac4a3af549503bb08cd309672fcada1030c5a494850e87ce5d4c613",
  "created_at": "2024-06-14T09:36:06.781306362Z",
  "access_grants": [
    {
      "principal_kind": "agent",
      "resource_kind": "virtual_cluster",
      "resource_id": "vci_1d4930d7_8e6d_4ad9_b27a_654ed4aaa3ee"
    }
  ]
}

Schema Registry Agent Key

If you are creating an agent key for WarpStream's BYOC Schema Registry, you must set virtual_cluster_type to byoc_schema_registry as follows:

curl https://api.warpstream.com/api/v1/create_api_key \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{"name":"example_agent_key", "virtual_cluster_type": "byoc_schema_registry", "access_grants": [
    {"principal_kind": "agent", "resource_kind": "virtual_cluster", "resource_id": "vci_sr_1d4930d7_8e6d_4ad9_b27a_654ed4aaa3ee"}
]}'

Cluster-Scoped Application Key

An application key is workspace-wide by default, but it can instead be scoped to a single resource on a single virtual cluster. Such a key is rejected by every other endpoint, and by those same endpoints on every other cluster. The example below creates an application key that can only manage topics on one virtual cluster.

Pick a resource_kind that the cluster named by resource_id actually supports. WarpStream does not check this when the key is created, so a mismatched grant produces a key that cannot do anything. For example, Tableflow clusters do not support any of these resource kinds.

Request

curl https://api.warpstream.com/api/v1/create_api_key \
-H 'warpstream-api-key: XXXXXXXXXX' \
-H 'Content-Type: application/json' \
-d '{"name":"example_topics_key", "access_grants": [
    {"principal_kind": "app", "resource_kind": "virtual_cluster_topics", "resource_id": "vci_1d4930d7_8e6d_4ad9_b27a_654ed4aaa3ee"}
]}'

Response

{
  "id": "aki_5c0a9e12_74b1_4f3e_9c6a_8d21b7e4f905",
  "name": "akn_example_topics_key",
  "key": "aks_3f8c1d9b5e2a47c0b6d84f1e9a705c3d2b8f6a41c9e5d073b2f8a1c64e9d70b5",
  "created_at": "2026-08-11T14:02:31.118204513Z",
  "access_grants": [
    {
      "principal_kind": "app",
      "resource_kind": "virtual_cluster_topics",
      "resource_id": "vci_1d4930d7_8e6d_4ad9_b27a_654ed4aaa3ee"
    }
  ]
}