--- title: "Upsert a Certificate" method: PUT path: "/v2/control-planes/{controlPlaneId}/core-entities/certificates/{CertificateId}" tags: ["Certificates"] --- # Upsert a Certificate `PUT /v2/control-planes/{controlPlaneId}/core-entities/certificates/{CertificateId}` ## Request - Base URL: `https://global.api.konghq.com` - URL: `https://global.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/certificates/{CertificateId}` - Auth: one of: - HTTP bearer - HTTP bearer - HTTP bearer - HTTP bearer Create or Update Certificate using ID. ## Request body - union - object: Certificate defined by its vault. - `cert` string: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `cert_alt` string, nullable: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `created_at` integer, nullable: Unix epoch when the resource was created. - `description` string, nullable: User-defined entity description. Konnect only field, not synced to the Gateway. - `id` string, nullable: A string representing a UUID (universally unique identifier). - `key` string: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `key_alt` string, nullable: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `managed_by` object: Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character. - `snis` string[], nullable - `tags` string[], nullable: An optional set of strings associated with the Certificate for grouping and filtering. - `updated_at` integer, nullable: Unix epoch when the resource was last updated. - `vault` string, nullable, required: Shorthand that expands into cert and key; when both vault and cert/key are provided, the vault expansion takes precedence. - `vault_alt` string, nullable: Shorthand that expands into cert_alt and key_alt; when both vault_alt and cert_alt/key_alt are provided, the vault_alt expansion takes precedence. - object: Certificate defined by its cert, key. - `cert` string, required: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `cert_alt` string, nullable: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `created_at` integer, nullable: Unix epoch when the resource was created. - `description` string, nullable: User-defined entity description. Konnect only field, not synced to the Gateway. - `id` string, nullable: A string representing a UUID (universally unique identifier). - `key` string, required: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `key_alt` string, nullable: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `managed_by` object: Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character. - `snis` string[], nullable - `tags` string[], nullable: An optional set of strings associated with the Certificate for grouping and filtering. - `updated_at` integer, nullable: Unix epoch when the resource was last updated. - `vault` string, nullable: Shorthand that expands into cert and key; when both vault and cert/key are provided, the vault expansion takes precedence. - `vault_alt` string, nullable: Shorthand that expands into cert_alt and key_alt; when both vault_alt and cert_alt/key_alt are provided, the vault_alt expansion takes precedence. ## Response `200` Successfully upserted Certificate - Certificate: A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string according to the following order: main certificate on the top, followed by any intermediates. - `cert` string, required: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `cert_alt` string, nullable: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `created_at` integer, nullable: Unix epoch when the resource was created. - `id` string, nullable: A string representing a UUID (universally unique identifier). - `key` string, required: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `key_alt` string, nullable: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). - `snis` string[], nullable - `tags` string[], nullable: An optional set of strings associated with the Certificate for grouping and filtering. - `updated_at` integer, nullable: Unix epoch when the resource was last updated. ## Other responses - `401`: Unauthorized ## Changes - **2026-10-15** `7aab863a6daa`: 1 breaking, 1 info - removed `subschema #1, subschema #2` from the `allOf[subschema #2]/` request property `anyOf` list - added `subschema #1: CertificateWithVault, subschema #2: CertificateWithCertAndKey` to the `allOf[subschema #2]/` request property `anyOf` list - **2026-08-12** `fbe6ce110ba4`: 1 breaking - the request property `allOf[subschema #1]/managed_by` became not nullable - **2026-06-23** `bb5e056b7c6d`: 2 breaking, 9 warning - added `subschema #1, subschema #2` to the request body `allOf` list - the request's body type changed from `object` to no type - removed the request property `cert` - removed the request property `cert_alt` - …7 more - **2025-07-22** `76b0fefddb0d`: 1 breaking, 1 info - the response property `tags` became nullable for the status `200` - the request property `tags` became nullable [Operation history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v2/control-planes/:controlPlaneId/core-entities/certificates/:CertificateId/put.md) --- [API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/7aab863a6daa?raw)