Create or Replace an SSL Certificate

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

SSL configuration body for create / replace / patch.

SSL certificate configuration for TLS termination or mTLS.

id?|

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

desc?string

Description.

Lengthlength <= 256

labels?

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

type?string

Certificate type.

Default"server"

Value in

"server"
"client"

sni?string

Server Name Indication (SNI) to match. Supports wildcard prefix (*.example.com). Mutually exclusive with snis.

snis?array<string>

Multiple SNI hostnames. Mutually exclusive with sni.

Items1 <= items

cert?string

PEM-encoded server certificate. Can also be a secret reference ($secret://...).

Length128 <= length <= 65536

key?string

PEM-encoded private key. Can also be a secret reference ($secret://...). Not returned in GET responses for security.

Length128 <= length <= 65536

certs?array<string>

Additional certificates for certificate chain or alternative key types.

keys?array<string>

Additional private keys corresponding to certs.

client?

mTLS client verification settings.

status?integer

SSL status.

Default1

Value in

ssl_protocols?array<>

Allowed TLS protocol versions.

Itemsitems <= 3

Response Body

`application/json`

curl -X PUT "http://127.0.0.1:9180/apisix/admin/ssls/my-resource-1?ttl=3600" \  -H "Content-Type: application/json" \  -d '{    "type": "server",    "sni": "api.example.com",    "cert": "-----BEGIN CERTIFICATE-----\\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\\n-----END CERTIFICATE-----\\n",    "key": "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe\\nfakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo\\npeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo\\npeNopeNopeNopeNopeNopeNope==\\n-----END PRIVATE KEY-----\\n"  }'

Created

{
  "key": "/apisix/ssls/1",
  "value": {
    "type": "server",
    "key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDh5cAWYXAMPLEbe\nfakekeyForOpenAPISpecPlaceholderOnlyDoNotUseForRealKeysNopeNopeNo\npeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNopeNo\npeNopeNopeNopeNopeNopeNope==\n-----END PRIVATE KEY-----\n",
    "snis": [
      "test.com"
    ],
    "id": "1",
    "create_time": 1684373523,
    "status": 1,
    "cert": "-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUJ9hQk3kXgZeZpY/m/0V6RmH1AbcwDQYJKoZIhvcNAQEL\nBQAwRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM\nGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMB4XDTI1MDEwMTAwMDAwMFoXDTM1\nMDEwMTAwMDAwMFowRTELMAkGA1UEBhMCVVMxEzARBgNVBAgMClNvbWUtU3RhdGUx\nITAfBgNVBAoMGEludGVybmFsIFJvb3QgQ0EgKGV4YW1wbGUpMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4eXAMPLEcaPUBLIcfakeforopeNAPIspecON\nLYexampleCAcontentsoExpandedFakeKeyMaterial==\n-----END CERTIFICATE-----\n",
    "update_time": 1684373523
  }
}

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

Create or Replace an SSL Certificate

Upload a new SSL certificate with a specified ID, or replace an existing one.

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

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

Responses

201: Created
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.

cURL

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

Create or Replace an SSL Certificate

201application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`