# 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 `application` or `agent`. These correspond to application keys and agent keys respectively.
* `resource_kind` may be `*` or `virtual_cluster`. For now, `*` is only supported for grants with principal kind `application`. `virtual_cluster` is only supported for grants with principal kind `agent`.
* `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 `*`.

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