Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Create (generate or import) a certificate
Implemented: mode=import only. The PEM bundle (leaf first, then intermediates) and
its unencrypted RSA-2048/RSA-4096/EC-P256 private key are validated, stored in Barbican as a PKCS12
secret by the project's platform credential and recorded synchronously; the private key is never
stored by the platform or returned. mode=generate is refused 422 (field mode): the platform does
not issue certificates. A malformed, mismatched, encrypted or expired bundle is 422 on the
offending field.
Creates a new TLS certificate record in the active scope from the certificate creation form.
Two modes are supported: generate (the platform builds a CSR from name/CN/SANs/key algorithm
and submits it to the selected issuer — platform managed CA, Let's Encrypt ACME, or external CSR
export) and import (the caller pastes an existing certificate PEM bundle plus its private key
PEM). On acceptance the certificate becomes discoverable in the scoped certificate list in a
transitional state while issuance/import completes.
Validation: name must match ^[a-z0-9-]{1,64}$ (lowercase letters, digits, hyphens) →
422 VALIDATION_FAILED; in generate mode commonName is required and keyAlgorithm must be a
non-symmetric algorithm (RSA-2048|RSA-4096|EC-P256); in import mode certificatePem and
privateKeyPem must each begin with a -----BEGIN PEM block → 422; duplicate certificate name
in the scope or scope certificate quota exhausted → 409; referenced issuer must be available.
Async & state: Asynchronous; returns 202 with the full Certificate resource in its
transitional (issuing/importing) state. Terminal states surface as status valid|expiring|expired;
progress is emitted as resource.updated SSE frames (kind: certificate, patch: status/serial/
notBefore/notAfter/thumbprints) until issuance completes.
Errors: 401 unauthenticated; 403 caller lacks contributor/admin/owner on the scope;
404 unknown scopeId; 409 quota exceeded or duplicate name; 422 invalid name/CN/PEM input;
500 internal failure.
Idempotency/Concurrency: Idempotency-Key is required; replays with the same key return the
original 202 result without creating a second certificate.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
The certificate creation form submission. mode=generate uses commonName/sans/keyAlgorithm/issuer to build and submit a CSR; mode=import uses certificatePem/privateKeyPem. The private key is write-only and never returned by any read.
name*stringFriendly certificate name in the vault (lowercase letters, digits, hyphens; max 64 chars).
^[a-z0-9-]{1,64}$mode*stringCreation method selected in the UI (Generate vs Import PEM).
"generate""import"commonName?stringPrimary hostname (CN), e.g. api.acme.io. Required when mode=generate.
sans?array<string>Additional hostnames the certificate should cover (generate mode), e.g. www.acme.io or *.acme.io.
keyAlgorithm?stringKey algorithm for the generated key pair (generate mode; AES-256 is not valid for certificates).
"RSA-2048""RSA-4096""EC-P256"issuer?stringIssuer selection (generate mode): platform managed CA, Let's Encrypt (ACME), or export CSR to sign externally.
"managed""lets-encrypt""csr"certificatePem?stringLeaf certificate followed by any intermediates, PEM-encoded. Required when mode=import.
privateKeyPem?stringPrivate key PEM. Required when mode=import; stored encrypted and never displayed again.
autoRenew?booleanRenew automatically before expiry and rotate on the load balancer with no downtime. Defaults to true.
tags?array<>Initial key/value tags.
items <= 50Create accepted; certificate returned in its transitional issuing/importing state.
application/json- response
TLS certificate read model backing the Certificates page and the certificate detail page. Contains public material and metadata only — the private key is write-only at import time and never appears here.
id*stringStable certificate identifier.
name*stringFriendly name in the vault (lowercase letters, digits, hyphens; max 64 chars).
subjectCn*stringSubject common name (primary hostname), e.g. api.acme.io.
sans*array<string>Subject alternative names (DNS names, possibly wildcards) the certificate covers.
issuer*stringFull issuer distinguished name (DN).
issuerCn*stringIssuer common name shown in lists.
status*stringLifecycle status derived from the validity window and revocation.
"valid""expiring""expired"origin*stringHow the certificate entered the vault.
"IMPORTED""MANAGED""CSR"notBefore*stringStart of the validity window (ISO 8601).
date-timenotAfter*stringEnd of the validity window (ISO 8601).
date-timeserial*stringCertificate serial number (colon-separated uppercase hex).
thumbprintSha1*stringSHA-1 thumbprint (colon-separated uppercase hex).
thumbprintSha256*stringSHA-256 thumbprint (colon-separated uppercase hex).
keyAlgorithm*stringKey algorithm of the certificate's key pair (KeyAlgo).
"RSA-2048""RSA-4096""EC-P256""AES-256"signatureAlgorithm*stringSignature algorithm identifier, e.g. SHA256-RSA or ECDSA-SHA256.
autoRenew*booleanWhether the platform renews the certificate automatically before expiry.
chain*array<>Trust chain from the leaf to a trusted root.
activity*array<>Recent lifecycle activity entries for the certificate.
tags*array<>Key/value tags for cost allocation and organization.
curl -X POST "https://example.com/scopes/string/keys/certificates" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "mode": "generate" }'{ "id": "string", "name": "string", "subjectCn": "string", "sans": [ "string" ], "issuer": "string", "issuerCn": "string", "status": "valid", "origin": "IMPORTED", "notBefore": "2019-08-24T14:15:22Z", "notAfter": "2019-08-24T14:15:22Z", "serial": "string", "thumbprintSha1": "string", "thumbprintSha256": "string", "keyAlgorithm": "RSA-2048", "signatureAlgorithm": "string", "autoRenew": true, "chain": [ { "cn": "string", "kind": "Leaf" } ], "activity": [ { "id": "string", "at": "2019-08-24T14:15:22Z", "action": "string", "actor": "string", "detail": "string", "status": "SUCCESS" } ], "tags": [ { "key": "string", "value": "string" } ]}