Create or Replace a Credential

PUT /apisix/admin/consumers/{username}/credentials/{id}

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

Path Parameters

username*string

Consumer username.

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

Length1 <= length <= 256

id*string

Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.

Query Parameters

ttl?integer

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

Range1 <= value

Request Body

application/json

Credential configuration body for create / replace / patch.

Credential configuration. Stores exactly one authentication plugin for a consumer.

id?|

Unique identifier for the resource. Can be a string (1–64 characters, alphanumeric with -, _, .) or a positive integer.

name?string

Human-readable name.

Length1 <= length <= 256

desc?string

Description of this credential.

Lengthlength <= 256

labels?

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

plugins?

Exactly one authentication plugin configuration (e.g., key-auth, basic-auth, jwt-auth).

Propertiesproperties <= 1

Response Body

`application/json`

curl -X PUT "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "plugins": {      "key-auth": {        "key": "credential-secret-key-456"      }    }  }'

Created

{
  "key": "/apisix/consumers/john/credentials/cred-john-key-auth",
  "value": {
    "create_time": 1725991703,
    "id": "cred-john-key-auth",
    "plugins": {
      "key-auth": {
        "key": "john-key"
      }
    },
    "update_time": 1725991703
  }
}

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/{username}/credentials/{id}

Create or Replace a Credential

Create a new credential for a consumer with a specified ID, or replace an existing one.

Each credential holds exactly one authentication plugin.

Parameters

username (path, string, required): Consumer username.
id (path, string, required): Unique identifier of the resource. Can be a string (alphanumeric, -, _, .) or a positive integer.
ttl (query, integer, optional): Time-to-live in seconds. The resource is automatically removed when it expires.

Request body

Credential configuration body for create / replace / patch.

Content type: application/json

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
name (string, optional): Human-readable name.
desc (string, optional): Description of this credential.
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.
plugins (object, optional): Exactly one authentication plugin configuration (e.g., key-auth, basic-auth, jwt-auth).

Responses

201: Created
key (string, required):
value (object, required): Credential configuration. Stores exactly one authentication plugin for a consumer.
value.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
value.name (string, optional): Human-readable name.
value.desc (string, optional): Description of this credential.
value.labels (object, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
value.create_time (integer, optional): Unix timestamp of creation. Read-only.
value.update_time (integer, optional): Unix timestamp of last update. Read-only.
value.plugins (object, optional): Exactly one authentication plugin configuration (e.g., key-auth, basic-auth, jwt-auth).
createdIndex (integer, optional):
modifiedIndex (integer, optional):
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 -X PUT 'http://127.0.0.1:9180/apisix/admin/consumers/{username}/credentials/{id}'

Create or Replace a Credential

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`