Compute

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

POST
/scopes/{scopeId}/compute/key-pairs

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.

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

Optional; 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.

Formatuuid

Request Body

application/json
  1. body

Create/import form payload from the key pair creation form. Region is derived from the active scope.

name*string

Key pair name; lowercase letters, digits and hyphens, up to 63 chars; unique within the region.

Match^[a-z0-9][a-z0-9-]{0,62}$
keyType*string

SSH (ED25519/RSA) for Linux sign-in, or X.509 certificates for Windows / mTLS.

Value in"ssh""x509"
source*string

generate lets the platform create the key material; import registers a caller-supplied public key.

Value in"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.

Response Body

Key pair created. For generated keys, privateKeyPem is revealed once in this response only.

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

Key pair identifier (e.g. "kp-1").

name*string

Key pair name, unique within the region.

fingerprint*string

SHA256 fingerprint of the public key (e.g. "SHA256:Hk9c…").

type*string

OpenSSH key algorithm.

Value in"ssh-ed25519""ssh-rsa""ecdsa-sha2-nistp256"
bits*integer

Key size in bits (256 for Ed25519/ECDSA P-256, e.g. 4096 for RSA).

createdAt*string

ISO-8601 creation timestamp.

publicKey*string

Full OpenSSH public key blob (algorithm, base64 material, comment).

comment*string

Key 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"}