Update a Secret (Partial)

PATCH /apisix/admin/secrets/{secret_type}/{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

secret_type*string

Type of secret manager (e.g., vault, aws).

Value in

"vault"
"aws"
"gcp"

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

Fields to merge into the existing secret-manager configuration.

Partial update for an existing Secret. APISIX recursively merges object fields, replaces arrays, and removes an object field when its value is null. The merged resource is then validated against the complete Secret schema.

HashiCorp Vault secret-manager configuration.

uri?|

Vault server URI.

Formaturi

prefix?|

Path prefix for secrets in Vault.

token?|

Vault authentication token or environment-variable URI.

namespace?|

Vault Enterprise or HCP Vault namespace.

Response Body

`application/json`

curl -X PATCH "http://127.0.0.1:9180/apisix/admin/secrets/vault/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "token": "$ENV://VAULT_TOKEN"  }'

Successful response.

{
  "value": {
    "token": "apisix",
    "id": "vault/1",
    "uri": "https://localhost/vault",
    "prefix": "/apisix/kv",
    "update_time": 1684396605,
    "create_time": 1684395392
  },
  "key": "/apisix/secrets/vault/1"
}

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"
}

Key not found

{
  "error_msg": "Key not found"
}

Complete operation details and schema variants

PATCH /apisix/admin/secrets/{secret_type}/{id}

Update a Secret (Partial)

Partially update a secret manager configuration.

Parameters

secret_type (path, string, required): Type of secret manager (e.g., vault, aws).
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

Fields to merge into the existing secret-manager configuration.

Content type: application/json

anyOf variant 1
uri (string,null, optional): Vault server URI.
prefix (string,null, optional): Path prefix for secrets in Vault.
token (string,null, optional): Vault authentication token or environment-variable URI.
namespace (string,null, optional): Vault Enterprise or HCP Vault namespace.
anyOf variant 2
access_key_id (string,null, optional): AWS access key ID or environment-variable URI.
secret_access_key (string,null, optional): AWS secret access key or environment-variable URI.
session_token (string,null, optional): Optional AWS session token or environment-variable URI.
region (string,null, optional): AWS region.
endpoint_url (string,null, optional): Custom AWS Secrets Manager endpoint.
anyOf variant 3
auth_config (object,null, optional):
auth_config.client_email (string,null, optional):
auth_config.private_key (string,null, optional):
auth_config.project_id (string,null, optional):
auth_config.token_uri (string,null, optional):
auth_config.scope (array,null, optional):
auth_config.entries_uri (string,null, optional):
ssl_verify (boolean,null, optional):
auth_file (string,null, optional): Path to a Google service-account JSON file.

Responses

200: Successful response.
key (string, optional): Unique key identifier for this secret in the data store.
value (object, optional): Secret values.
value.id (string, optional): Unique identifier for the secret configuration, including the secret manager type and ID.
value.prefix (string, optional): Path prefix for the secret engine or storage location.
value.token (string, optional): Authentication token or credential for accessing the secret manager.
value.create_time (integer, optional): Creation time of the secret.
value.update_time (integer, optional): Update time of the secret.
value.uri (string, optional): Endpoint URI of the secret manager service.
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.
404: Not Found — The specified resource does not exist.
error_msg (string, required): Error message indicating the resource was not found.

cURL

curl -X PATCH 'http://127.0.0.1:9180/apisix/admin/secrets/{secret_type}/{id}'

Update a Secret (Partial)

200application/json

400application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`