API7 Docs

Update an SSL Certificate (Partial)

PATCH /apisix/admin/ssls/{id}

PATCH /apisix/admin/ssls/{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

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 SSL. Object fields are merged recursively; arrays are replaced.

Partial update for an existing SSL. 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 SSL schema.

Response Body

application/json

application/json

application/json

application/json

curl -X PATCH "http://127.0.0.1:9180/apisix/admin/ssls/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "snis": [      "api.example.com",      "admin.example.com"    ]  }'

Successful response.

{
  "key": "string",
  "value": {
    "id": "my-route-1",
    "desc": "string",
    "labels": {
      "env": "production",
      "team": "platform",
      "version": "v2"
    },
    "create_time": 0,
    "update_time": 0,
    "sni": "api.example.com",
    "snis": [
      "string"
    ],
    "cert": "stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringst",
    "key": "stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringst",
    "certs": [
      "string"
    ],
    "keys": [
      "string"
    ],
    "client": {
      "ca": "stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringst",
      "depth": 1,
      "skip_mtls_uri_regex": [
        "string"
      ]
    },
    "status": 1,
    "ssl_protocols": [
      "TLSv1.1"
    ],
    "type": "server"
  },
  "createdIndex": 0,
  "modifiedIndex": 0
}
Complete operation details and schema variants

PATCH /apisix/admin/ssls/{id}

Update an SSL Certificate (Partial)

Partially update an SSL certificate's configuration. Only the fields included in the request body are modified; all other fields remain unchanged.

Parameters

  • 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 SSL. Object fields are merged recursively; arrays are replaced.

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
  • anyOf variant 3
  • desc (string,null, optional): Description.
  • labels (object,null, optional): Key-value pairs for categorizing and filtering resources. Values must be non-empty strings (max 256 characters).
  • create_time (integer,null, optional): Unix timestamp of creation. Read-only.
  • update_time (integer,null, optional): Unix timestamp of last update. Read-only.
  • type (string,null, optional): Certificate type.
  • sni (string,null, optional): Server Name Indication (SNI) to match. Supports wildcard prefix (*.example.com). Mutually exclusive with snis.
  • snis (array,null, optional): Multiple SNI hostnames. Mutually exclusive with sni.
  • cert (string,null, optional): PEM-encoded server certificate. Can also be a secret reference ($secret://...).
  • key (string,null, optional): PEM-encoded private key. Can also be a secret reference ($secret://...). Not returned in GET responses for security.
  • certs (array,null, optional): Additional certificates for certificate chain or alternative key types.
  • keys (array,null, optional): Additional private keys corresponding to certs.
  • client (object,null, optional): mTLS client verification settings.
  • client.ca (string,null, optional): PEM-encoded CA certificate for client verification.
  • client.depth (integer,null, optional): Maximum certificate chain depth.
  • client.skip_mtls_uri_regex (array,null, optional): URI regex patterns to skip mTLS verification.
  • status (integer,null, optional): SSL status.
  • ssl_protocols (array,null, optional): Allowed TLS protocol versions.

Responses

  • 200: Successful response.
  • key (string, required):
  • value (object, required): SSL certificate configuration for TLS termination or mTLS.

Read-only response variant: private keys (key, keys) are stripped from GET responses, so they are not present here.

  • 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.desc (string, optional): Description.
  • 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.type (string, optional): Certificate type.
  • value.sni (string, optional): Server Name Indication (SNI) to match. Supports wildcard prefix (*.example.com). Mutually exclusive with snis.
  • value.snis (array, optional): Multiple SNI hostnames. Mutually exclusive with sni.
  • value.cert (string, optional): PEM-encoded server certificate. Can also be a secret reference ($secret://...).
  • value.key (string, optional): PEM-encoded private key. Can also be a secret reference ($secret://...). Not returned in GET responses for security.
  • value.certs (array, optional): Additional certificates for certificate chain or alternative key types.
  • value.keys (array, optional): Additional private keys corresponding to certs.
  • value.client (object, optional): mTLS client verification settings.
  • value.client.ca (string, required): PEM-encoded CA certificate for client verification.
  • value.client.depth (integer, optional): Maximum certificate chain depth.
  • value.client.skip_mtls_uri_regex (array, optional): URI regex patterns to skip mTLS verification.
  • value.status (integer, optional): SSL status.
  • value.ssl_protocols (array, optional): Allowed TLS protocol versions.
  • 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.
  • 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/ssls/{id}'

Get an SSL Certificate

Previous Page

Delete an SSL Certificate

Next Page