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 an SSH key pair in the active scope
Creates a key pair in the active scope. Two UI entry points collapse here: the
the key pair creation form submission and the "Create key pair" button on the Key pairs page (which opens
the same form; "Import key" opens it pre-set to import mode). The form captures the region
(read-only, scope-derived), the key pair name, the key type (ssh for ED25519/RSA over SSH on
Linux, x509 certificates for Windows / mTLS), and the source: generate asks the platform to
create the key material, import registers a public key the caller already owns (only the
public key is uploaded — the private key never leaves the client). On success the key pair
becomes discoverable in the scoped list.
Validation: name must match ^[a-z0-9][a-z0-9-]{0,62}$ (lowercase letters, digits,
hyphens, up to 63 chars — 422 VALIDATION_FAILED otherwise) and be unique within the region (409
CONFLICT on duplicates); keyType must be ssh or x509; source must be generate or
import; when source=import, publicKey is required and must be a valid OpenSSH public key
(ssh-ed25519 / ssh-rsa / ecdsa-… prefix) unless keyType=x509 (422 otherwise); scopeId
must be accessible (404 when unknown).
Async & state: Synchronous create returning 201 with the full KeyPairCreated resource. For
source=generate the response includes privateKeyPem — the ONLY time the private key is ever
returned; it is not stored by the platform and cannot be retrieved later (the UI forces a download of
the .pem before leaving the page). For source=import, privateKeyPem is null. The new key
pair is announced via a resource.updated SSE frame of kind compute.keyPair.
Errors: 401 unauthenticated; 403 caller lacks a write-capable role (owner|admin|contributor)
on the scope; 404 unknown scopeId; 409 duplicate name in the region; 422 invalid
name/keyType/source/publicKey; 500 key-generation or persistence failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended); replaying the same
key returns the
original 201 response — including the same privateKeyPem — instead of generating a second key
pair, so a UI retry cannot silently mint divergent key material.
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?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidapplication/json- body
Create/import form payload from the key pair creation form. Region is derived from the active scope.
name*stringKey pair name; lowercase letters, digits and hyphens, up to 63 chars; unique within the region.
^[a-z0-9][a-z0-9-]{0,62}$keyType*stringSSH (ED25519/RSA) for Linux sign-in, or X.509 certificates for Windows / mTLS.
"ssh""x509"source*stringgenerate lets the platform create the key material; import registers a caller-supplied public key.
"generate""import"publicKey?|OpenSSH public key to register; required when source=import and keyType=ssh (must start with ssh-ed25519 / ssh-rsa / ecdsa-…). Only the public key is uploaded — the private key never leaves the client. Null when source=generate.
Key pair created. For generated keys, privateKeyPem is revealed once in this response only.
application/json- response
Creation response. For source=generate it carries the PEM-encoded private key exactly once — it is not stored by the platform and can never be retrieved again (the UI forces a .pem download before leaving the page). Null for imported keys.
id*stringKey pair identifier (e.g. "kp-1").
name*stringKey pair name, unique within the region.
fingerprint*stringSHA256 fingerprint of the public key (e.g. "SHA256:Hk9c…").
type*stringOpenSSH key algorithm.
"ssh-ed25519""ssh-rsa""ecdsa-sha2-nistp256"bits*integerKey size in bits (256 for Ed25519/ECDSA P-256, e.g. 4096 for RSA).
createdAt*stringISO-8601 creation timestamp.
publicKey*stringFull OpenSSH public key blob (algorithm, base64 material, comment).
comment*stringKey comment (e.g. "ops@publiccloud").
usedBy*array<>Instances currently configured with this key; non-empty blocks deletion.
privateKeyPem*|One-time PEM-encoded private key (OPENSSH PRIVATE KEY block); null when source=import.
curl -X POST "https://example.com/scopes/string/compute/key-pairs" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "keyType": "ssh", "source": "generate" }'{ "id": "string", "name": "string", "fingerprint": "string", "type": "ssh-ed25519", "bits": 0, "createdAt": "string", "publicKey": "string", "comment": "string", "usedBy": [ { "id": "string", "name": "string", "status": "ACTIVE" } ], "privateKeyPem": "string"}