Key & Certificate Management

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

POST
/scopes/{scopeId}/keys/certificates

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Header Parameters

Idempotency-Key*string

Required: 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.

Formatuuid

Request Body

application/json
  1. 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*string

Friendly certificate name in the vault (lowercase letters, digits, hyphens; max 64 chars).

Match^[a-z0-9-]{1,64}$
mode*string

Creation method selected in the UI (Generate vs Import PEM).

Value in"generate""import"
commonName?string

Primary 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?string

Key algorithm for the generated key pair (generate mode; AES-256 is not valid for certificates).

Value in"RSA-2048""RSA-4096""EC-P256"
issuer?string

Issuer selection (generate mode): platform managed CA, Let's Encrypt (ACME), or export CSR to sign externally.

Value in"managed""lets-encrypt""csr"
certificatePem?string

Leaf certificate followed by any intermediates, PEM-encoded. Required when mode=import.

privateKeyPem?string

Private key PEM. Required when mode=import; stored encrypted and never displayed again.

autoRenew?boolean

Renew automatically before expiry and rotate on the load balancer with no downtime. Defaults to true.

tags?array<>

Initial key/value tags.

Itemsitems <= 50

Response Body

Create accepted; certificate returned in its transitional issuing/importing state.

application/json
  1. 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*string

Stable certificate identifier.

name*string

Friendly name in the vault (lowercase letters, digits, hyphens; max 64 chars).

subjectCn*string

Subject common name (primary hostname), e.g. api.acme.io.

sans*array<string>

Subject alternative names (DNS names, possibly wildcards) the certificate covers.

issuer*string

Full issuer distinguished name (DN).

issuerCn*string

Issuer common name shown in lists.

status*string

Lifecycle status derived from the validity window and revocation.

Value in"valid""expiring""expired"
origin*string

How the certificate entered the vault.

Value in"IMPORTED""MANAGED""CSR"
notBefore*string

Start of the validity window (ISO 8601).

Formatdate-time
notAfter*string

End of the validity window (ISO 8601).

Formatdate-time
serial*string

Certificate serial number (colon-separated uppercase hex).

thumbprintSha1*string

SHA-1 thumbprint (colon-separated uppercase hex).

thumbprintSha256*string

SHA-256 thumbprint (colon-separated uppercase hex).

keyAlgorithm*string

Key algorithm of the certificate's key pair (KeyAlgo).

Value in"RSA-2048""RSA-4096""EC-P256""AES-256"
signatureAlgorithm*string

Signature algorithm identifier, e.g. SHA256-RSA or ECDSA-SHA256.

autoRenew*boolean

Whether 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"    }  ]}