> For the complete documentation index, see [llms.txt](https://docs.warpstream.com/warpstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warpstream.com/warpstream/reference/api-reference/api-keys/create.md).

# Create

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](#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](#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

{% code overflow="wrap" %}

```bash
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"}
]}'
```

{% endcode %}

## 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

{% code overflow="wrap" %}

```bash
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"}
]}'
```

{% endcode %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.warpstream.com/warpstream/reference/api-reference/api-keys/create.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.