Create or Replace a Secret

PUT /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

Complete secret-manager configuration for the manager selected by secret_type.

Secret-manager configuration. The body must match the manager selected by the secret_type path parameter.

HashiCorp Vault secret-manager configuration.

uri*string

Vault server URI.

Formaturi

prefix*string

Path prefix for secrets in Vault.

token*string

Vault authentication token or environment-variable URI.

namespace?string

Vault Enterprise or HCP Vault namespace.

Response Body

`application/json`

curl -X PUT "http://127.0.0.1:9180/apisix/admin/secrets/vault/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "uri": "https://vault.example.com",    "prefix": "apisix",    "token": "$ENV://VAULT_TOKEN",    "namespace": "team-a"  }'

Created

{
  "value": {
    "prefix": "/apisix/kv",
    "token": "343effad",
    "uri": "https://localhost/vault",
    "namespace": "apisix",
    "id": "vault/1",
    "update_time": 1684395392,
    "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"
}

Complete operation details and schema variants

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

Create or Replace a Secret

Configure a secret manager integration with a specified ID.

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

Complete secret-manager configuration for the manager selected by secret_type.

Content type: application/json

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

Responses

201: Created
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.namespace (string, optional): Used to set the namespace of HashiCorp Vault Enterprise and HCP Vault.
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.

cURL

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

Create or Replace a Secret

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`