# 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](/warpstream/reference/api-reference/api-keys/create#schema-registry-agent-key).

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](/warpstream/reference/api-reference/api-keys/create#cluster-scoped-application-key).
* `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

```bash wrap
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

```json
{
  "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:

```json
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

```bash wrap
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

```json
{
  "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"
    }
  ]
}
```