Sign in
Centrally Managed Consumers

Create a consumer

Create a new consumer in this Realm. It will be available to use for authentication within a few seconds, unless the consumer's username is blocked in the Gateway. If this is the case, the new consumer will be available in negative_ttl (see the Realm definition) seconds.

post/v1/realms/{realmId}/consumers

Request body

usernamestring required

The unique username of the Consumer.

custom_idstring

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database.

consumer_groupsstring[]

A list of consumer groups that the Consumer is in. If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

type'proxy' | 'developer' | 'admin' | 'application'

Type of the consumer.

tagsstring[]

Response

success

idstring uuid required

The Consumer ID.

usernamestring required

The unique username of the Consumer. You must send either this field or custom_id with the request.

custom_idstring nullable required

Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

type'proxy' | 'developer' | 'admin' | 'application' required

Type of the consumer.

tagsstring[] required
consumer_groupsstring[] required

A list of consumer groups that the Consumer is in. If consumer_groups are provided on the Consumer object and on the Realm, the Consumer will be placed in all defined consumer groups.

created_atstring date-time required

An ISO-8601 timestamp representation of entity creation date.

updated_atstring date-time required

An ISO-8601 timestamp representation of entity update date.

Example response

{
  "custom_id": "4200",
  "id": "8a388226-80e8-4027-a486-25e4f7db5d21",
  "type": "proxy",
  "consumer_groups": [
    "gold"
  ],
  "tags": [
    "partner"
  ],
  "username": "bob-the-builder",
  "created_at": "2025-06-17T16:55:58.569399532Z",
  "updated_at": "2025-06-17T16:55:58.569399532Z"
}

Changes

Changed in 3 of the 52 revisions of this API.511

  • 19e869275e281See the full diff
    • ●

      added the new type enum value to the allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterStandard]/rule response property for the response status 400

      response-property-enum-value-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 96118a9cd7f45See the full diff
    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterChoiceItem]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterDependentItem]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterMaximumLength]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterMinimumLength]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterStandard]/source became nullable for the status 400

      response-property-became-nullable

    This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9f695af251021See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog