---
title: "Create or update a certificate"
method: PUT
path: "/organizations/{orgId}/environments/{envId}/domains/{domainKey}/certificates"
tags: ["Certificates", "Domains"]
---

# Create or update a certificate

`PUT /organizations/{orgId}/environments/{envId}/domains/{domainKey}/certificates`

Idempotent create-or-update. Uses the key field in the body to identify the certificate within the domain. Re-applying an unchanged definition is a no-op. The system flag is immutable; changing it requires deleting and recreating the certificate.

## Path parameters

- `orgId` string, required
- `envId` string, required
- `domainKey` string, required

## Request body

- AutomationCertificate — A certificate managed under a domain by the Automation API. The key field is the stable, immutable identity used for idempotent create-or-update.
  - `configuration` string — Plugin-specific configuration as a JSON-encoded string. Its shape is defined by the selected certificate type.
  - `createdAt` string, date-time — Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.
  - `expiresAt` string, date-time — Expiry timestamp (ISO-8601 / RFC 3339, UTC), when known for the certificate type. Read-only.
  - `key` string, required — Stable, immutable identifier for the certificate within its domain. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. Used to identify the certificate on create-or-update.
  - `name` string — Human-readable name of the certificate.
  - `system` boolean — Whether this is the domain's system certificate. Immutable after creation. When true, only key is required; the certificate is built from the domains.certificates.default.* system settings and the name, type, and configuration fields are ignored.
  - `type` string — Certificate plugin type identifier. Immutable after creation.
  - `updatedAt` string, date-time — Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

## Response `200`

The created or updated certificate

- AutomationCertificate — A certificate managed under a domain by the Automation API. The key field is the stable, immutable identity used for idempotent create-or-update.
  - `configuration` string — Plugin-specific configuration as a JSON-encoded string. Its shape is defined by the selected certificate type.
  - `createdAt` string, date-time — Creation timestamp (ISO-8601 / RFC 3339, UTC). Read-only.
  - `expiresAt` string, date-time — Expiry timestamp (ISO-8601 / RFC 3339, UTC), when known for the certificate type. Read-only.
  - `key` string, required — Stable, immutable identifier for the certificate within its domain. Lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. Used to identify the certificate on create-or-update.
  - `name` string — Human-readable name of the certificate.
  - `system` boolean — Whether this is the domain's system certificate. Immutable after creation. When true, only key is required; the certificate is built from the domains.certificates.default.* system settings and the name, type, and configuration fields are ignored.
  - `type` string — Certificate plugin type identifier. Immutable after creation.
  - `updatedAt` string, date-time — Last-update timestamp (ISO-8601 / RFC 3339, UTC). Read-only.

## Other responses

- `400` — Invalid request: a key conflict, a missing required field for a non-system certificate, an attempt to change the immutable system flag, or a second system certificate for the domain
- `403` — Permission denied
- `404` — Domain not found, or not managed by the Automation API

---

[API](https://skmtc.net/gravitee-io/apis/gravitee-io-am-automation-api.md) · [All operations](https://skmtc.net/gravitee-io/apis/gravitee-io-am-automation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gravitee-io/gravitee-io-am-automation-api/revisions/39ed35bd3858/schema)