secutils-dev/secutils/private-keys

Secutils.dev: Private Keys

The Private Keys utility stores user-generated asymmetric keypairs on the server, optionally encrypted with a user-chosen passphrase. Keys can be exported on demand in PKCS#8 DER, PKCS#8 PEM, or legacy PEM, and can be used as the keypair behind a Secutils certificate template (see secutils-certificate-templates). The guide lives at <https://secutils.dev/docs/guides/digital_certificates/private_keys> and the full API reference at <https://secutils.dev/api-docs/openapi.json>.

Endpoints (tag: certificates)

The list endpoint never returns key material; only metadata (id, name, alg, encrypted, createdAt, updatedAt, tags) is exposed. The raw key bytes are only available via _export.

Authentication

Use either the ory_kratos_session cookie obtained from <https://secutils.dev/signin> or an Authorization: Bearer su_ak_<token> header from an API key created in Settings → Security (see secutils-api-keys).

Create-key payload

POST /api/certificates/private_keys accepts PrivateKeysCreateParams (camelCase JSON):

{
  "keyName": "my-key",
  "alg": { "keyType": "ed25519" },
  "passphrase": null,
  "tagIds": []
}

alg is a tagged union driven by keyType:

Notes:

• keySize is sent as a string, not an integer (matches the OpenAPI

schema enum).

• passphrase is optional. When present the server encrypts the key at

rest with AES-256-GCM; export must then supply the matching passphrase. When omitted the key is stored unencrypted on the server but never surfaced through any list or get endpoint.

• tagIds is the list of Workspace tag IDs to associate (see

secutils-tags).

POST returns the newly created PrivateKey with its server-assigned id.

Export payload

POST /api/certificates/private_keys/{key_id}/_export body:

{
  "format": "pkcs8",            // "pkcs8" | "pem"
  "passphrase": "current-pass", // required iff the key was created with one
  "exportPassphrase": "new-pass" // optional; if set, re-encrypts on export
}

Successful response is application/octet-stream containing the raw key bytes. pkcs8 produces a binary PKCS#8 DER blob (typical filename Key.p8), pem produces a base64-armoured PEM (-----BEGIN ...-----). If exportPassphrase is supplied the exported file is encrypted with that passphrase regardless of how the key was stored, which is the standard way to share an encrypted key with another user.

Example flow (curl)

# Generate an Ed25519 key without a passphrase
curl -sX POST https://secutils.dev/api/certificates/private_keys \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"keyName":"ed25519-test","alg":{"keyType":"ed25519"},"tagIds":[]}'
 
# Generate a 2048-bit RSA key, passphrase-protected
KEY=$(curl -sX POST https://secutils.dev/api/certificates/private_keys \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"keyName":"rsa-2048","alg":{"keyType":"rsa","keySize":"2048"},"passphrase":"s3cret","tagIds":[]}')
ID=$(echo "$KEY" | jq -r '.id')
 
# Export as PEM, decrypted, for use with openssl
curl -sX POST "https://secutils.dev/api/certificates/private_keys/$ID/_export" \
  -H "Authorization: Bearer $SECUTILS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"format":"pem","passphrase":"s3cret"}' \
  -o rsa.pem
openssl pkey -in rsa.pem -text -noout

Update vs regenerate

PUT /api/certificates/private_keys/{key_id} accepts a PrivateKeysUpdateParams body that can change keyName, change the passphrase (must include the existing passphrase to authenticate the change), or update tagIds. There is no key rotation operation; if a key needs new material, delete it and create a new one.

Caveats

• Asymmetric algorithm choice cannot be changed after creation. Pick the

right alg up front.

• The server never returns plaintext key bytes from GET endpoints. The

only way to retrieve the bytes is _export with the correct passphrase.

• Deleting a key that is referenced by a certificate template only

detaches the reference; the template then has no keypair until a new one is supplied.

• The alg.keySize value is a quoted string in the JSON schema (e.g.

"2048"). Passing it as a JSON number returns 400 Bad Request.

• For storing the matching certificate, generate a certificate template

bound to this key with the secutils-certificate-templates skill.

See also

• Human-readable guide: <https://secutils.dev/docs/guides/digital_certificates/private_keys>
• Related skill: secutils-certificate-templates (for X.509 issuance)
• OpenAPI: <https://secutils.dev/api-docs/openapi.json>