---
title: "Create a key"
method: POST
path: "/v1/realms/{realmId}/consumers/{consumerId}/keys"
tags: ["Centrally Managed Keys"]
---

# Create a key

`POST /v1/realms/{realmId}/consumers/{consumerId}/keys`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v1/realms/{realmId}/consumers/{consumerId}/keys`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
- TypeScript: <https://skmtc.dev/kong/apis/konnect-api/docs/v1/realms/:realmId/consumers/:consumerId/keys/post.ts> (a function with typed inputs; its response is checked against the schema)

This operation generates an API key for the specified consumer. The key is returned only at the time of creation
and will not be retrievable in any subsequent GET requests on the entity.

The API supports two key creation types: `new` and `legacy`.

* `new`: The recommended and more efficient option. The API automatically generates the key and returns it during
this operation.
* `legacy`: Allows you to provide your own secret. This approach has a performance impact when proxying requests, as it involves
additional processing and resource usage.

Note: Regardless of the type selected, the key is only returned by the API when a key is created. It is not retrievable in the future.

## Request body

- CreateApiKeyPayload
  - `type` 'new' | 'legacy', required
  - `secret` string: secret to be created. Must be unique within the realm. If not specified a secret will be automatically generated.
  - `tags` string[]

## Response `201`

success

- CreateApiKeyResult
  - `id` string, required
  - `type` 'legacy' | 'new', required
  - `secret` string, required
  - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date.
  - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity update date.
  - `tags` string[], required

## Other responses

- `400`: Bad Request
- `404`: Not Found

## Changes

- **2026-10-23** `30af8b28f6ef`: 1 breaking, 2 warning
  - added `#/components/schemas/InvalidParameterMinimumTime, #/components/schemas/InvalidParameterMaximumTime` to the `invalid_parameters/items/` response property `oneOf` list for the response status `400`
  - added the new `key_invalid` enum value to the `invalid_parameters/items/oneOf[#/components/schemas/InvalidParameterStandard]/rule` response property for the response status `400`
  - added the new `unique` enum value to the `invalid_parameters/items/oneOf[#/components/schemas/InvalidParameterStandard]/rule` response property for the response status `400`
- **2026-09-30** `f530bf400198`: 2 warning
  - added the new `400.00` enum value to the `status` response property for the response status `400`
  - added the new `404.00` enum value to the `status` response property for the response status `404`
- **2026-09-25** `4a02153f2e60`: 2 breaking, 13 info
  - the response's body type changed from no type to `object` for status `400`
  - the response's body type changed from no type to `object` for status `404`
  - removed `#/components/schemas/BaseError, subschema #2` from the response body `allOf` list for the response status `400`
  - removed `#/components/schemas/BaseError, subschema #2` from the response body `allOf` list for the response status `404`
  - …11 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/kong/apis/konnect-api/changes/v1/realms/:realmId/consumers/:consumerId/keys/post.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api.md) - [All operations](https://skmtc.dev/kong/apis/konnect-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api/revisions/f018071a4515?raw)