Create or Update a Consumer

PUT /apisix/admin/consumers

Interactive request editor loads with JavaScript.

Authorization

X-API-KEY<token>

Admin API key configured in config.yaml under deployment.admin.admin_key. You can also pass the key as a query parameter api_key or cookie x_api_key.

In: header

Query Parameters

ttl?integer

Time-to-live in seconds. The resource is automatically removed when it expires.

Range1 <= value

Request Body

application/json

Consumer configuration body for create / replace / patch.

Consumer configuration. Represents an API user or application with authentication credentials and plugin policies.

username*string

Unique username for the consumer. Only alphanumeric characters, hyphens, and underscores are allowed.

Match^[a-zA-Z0-9_\-]+$

Length1 <= length <= 256

desc?string

Description of this consumer.

Lengthlength <= 256

labels?

Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).

group_id?|

Reference to a Consumer Group for shared plugin configurations.

plugins?

Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{  "limit-count": {    "count": 100,    "time_window": 60  },  "key-auth": {}}

See the Plugin Hub for available plugins and their schemas.

Response Body

`application/json`

curl -X PUT "http://127.0.0.1:9180/apisix/admin/consumers?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "username": "my-app",    "desc": "Mobile application consumer",    "labels": {      "team": "mobile",      "env": "production"    },    "plugins": {      "key-auth": {        "key": "app-secret-key-123"      }    }  }'

Created

{
  "key": "/apisix/consumers/jack",
  "value": {
    "plugins": {
      "limit-count": {
        "time_window": 60,
        "rejected_code": 503,
        "key": "remote_addr",
        "key_type": "var",
        "count": 2,
        "show_limit_quota_header": true,
        "allow_degradation": false,
        "policy": "local"
      }
    },
    "username": "jack",
    "create_time": 1683164776,
    "update_time": 1684289832
  }
}

Invalid configuration

{
  "error_msg": "invalid configuration: property \"uri\" is required"
}

{
  "error_msg": "invalid request body: unexpected character at line 1 column 2"
}

**Unauthorized** — The API key is missing, invalid, or lacks permission.

{
  "error_msg": "failed to check token",
  "description": "missing apikey"
}

{
  "error_msg": "failed to check token",
  "description": "wrong apikey"
}

{
  "error_msg": "failed to check token",
  "description": "invalid method for role viewer"
}

Complete operation details and schema variants

PUT /apisix/admin/consumers

Create or Update a Consumer

Create a new consumer or update an existing one. The consumer is identified by username in the request body.

Parameters

ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Consumer configuration body for create / replace / patch.

Content type: application/json

username (string, required): Unique username for the consumer. Only alphanumeric characters, hyphens, and underscores are allowed.
desc (string, optional): Description of this consumer.
labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
create_time (integer, optional): Unix timestamp of creation. Read-only.
update_time (integer, optional): Unix timestamp of last update. Read-only.
group_id (object, optional): Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.
anyOf variant 1: String ID
anyOf variant 2: Integer ID
plugins (object, optional): Plugin configurations as a JSON object. Each key is a plugin name, and the value is that plugin's configuration object.

Example:

{
  "limit-count": {
    "count": 100,
    "time_window": 60
  },
  "key-auth": {}
}

See the Plugin Hub for available plugins and their schemas.

Responses

201: Created
key (string, optional): Unique key identifier for this consumer.
value (object, optional): Consumer values.
value.plugins (object, optional): Key-value pairs of plugins and their configurations on the object.
value.username (string, optional): The unique identifier of the consumer.
value.labels (object, optional): Key-value pairs to specify attributes.
value.desc (string, optional): Consumer description.
value.group_id (object, optional): Consumer group ID.
anyOf variant 1
anyOf variant 2
value.create_time (integer, optional): Creation time of the consumer.
400: Bad Request — The request body is invalid or missing required fields.
error_msg (string, required): Human-readable error message describing what went wrong.
401: Unauthorized — The API key is missing, invalid, or lacks permission.
error_msg (string, required): Authentication error message.
description (string, optional): Detailed reason for the authentication failure.

cURL

curl -i http://127.0.0.1:9180/apisix/admin/consumers \
  -H 'X-API-KEY: your-api-key' \
  -H 'Content-Type: application/json' \
  -X PUT -d '{
    "username": "my-app",
    "plugins": {
      "key-auth": {"key": "app-secret-key-123"}
    }
  }'

Create or Update a Consumer

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`