---
title: "API"
description: "The Certificates API's Private CA operations, asynchronous changes, idempotency and conditional writes."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API

The [Certificates API](/certificates-api) is at `https://certificates.ezghcloud.com`. Private CA's
routes are under `/v1/organizations/<org>/projects/<project>` and follow the platform's
[API conventions](/api): API keys or your console session, errors with a `code`, and cursor
pages.

## Operations

| What | Operations |
| --- | --- |
| Certificate authorities | [List](/certificates-api/ListCertificateAuthorities/), [create](/certificates-api/CreateCertificateAuthority/), [get](/certificates-api/GetCertificateAuthority/), [update](/certificates-api/UpdateCertificateAuthority/), [delete](/certificates-api/DeleteCertificateAuthority/), [disable](/certificates-api/DisableCertificateAuthority/), [enable](/certificates-api/EnableCertificateAuthority/), [restore](/certificates-api/RestoreCertificateAuthority/), [renew](/certificates-api/RenewCertificateAuthority/), [revoke](/certificates-api/RevokeCertificateAuthority/) |
| External subordinates | [Get the CSR](/certificates-api/GetCertificateAuthorityCsr/), [import the certificate](/certificates-api/ImportCertificateAuthorityCertificate/) |
| Issued certificates | [Issue](/certificates-api/IssueCertificate/), [list a CA's](/certificates-api/ListPrivateCertificates/), [list the project's](/certificates-api/ListAllPrivateCertificates/), [get](/certificates-api/GetPrivateCertificate/), [revoke](/certificates-api/RevokePrivateCertificate/), [export the key](/certificates-api/ExportCertificatePrivateKey/), [forget the key](/certificates-api/ForgetCertificatePrivateKey/), [delete](/certificates-api/DeletePrivateCertificate/) |
| ACME bindings | [List](/certificates-api/ListAcmeBindings/), [create](/certificates-api/CreateAcmeBinding/), [get](/certificates-api/GetAcmeBinding/), [delete](/certificates-api/DeleteAcmeBinding/) |

## Asynchronous changes

- Creating a CA, importing its certificate and renewing it answer `202` with
  `{resource, operation}`: the CA as it is now and the operation that finishes the change.
- Issuing from a generated key answers `202` with `{operation}`. Issuing from a CSR answers `201`
  with the certificate, or `202` with `{operation}` when signing takes longer.
- A retry with the same `Idempotency-Key` of any of these `202` answers gets the **operation
  alone**, as it is then: read the resource by the operation's `target`.

Follow an operation with `GET /v1/organizations/<org>/operations/<id>` until `finishedAt` is set;
its `target` is what it changed (for an issue, the new certificate). Never treat a `202` as done.

## Idempotency and conditional writes

- Send an `Idempotency-Key` on creates and changes: a retry with the same key and body gets the
  first answer instead of doing it twice. A retried ACME binding create answers `hmacKey: null`:
  the key is shown only to the first. Export-key takes no `Idempotency-Key`, so no copy of an
  exported key is kept for a replay.
- Changes to a CA or a certificate take its `ETag` as `If-Match`; a stale one answers `412`.

## Refusals

| Code | Meaning |
| --- | --- |
| `root_cannot_issue_leaves` | A root signs only subordinate CAs |
| `certificate_authority_inactive` | The CA isn't active (being created, waiting for its certificate, disabled or deleted) |
| `issuance_refused` | The CA's policy refused the certificate; `reason` says why (`name_constraints`, `validity`, …) and `message` names the name or limit |
| `no_key` | A certificate issued from your CSR has no key to export |
| `key_forgotten` | Its key was forgotten |
| `certificate_authority_in_use` | Subordinates or managed certificates still depend on the CA |
| `roots_are_not_revoked` | Disable or delete a root instead |
| `quota_exceeded` | A [quota](/private-ca/limits#quotas) was reached |

Source: https://docs.ezghcloud.com/private-ca/api/index.mdx