Key Management API

A unified interface for the complete cryptographic-key lifecycle

1. Purpose

The Key Management tag offers crypto-agile control over every key stored in ANKA Secure, from classical RSA/ECC to post-quantum ML-KEM / ML-DSA / Falcon / SLH-DSA and symmetric AES variants.
All endpoints are idempotent and follow RFC 7807 for errors.

2. Endpoints

HTTP Verb	Path	Function	Typical Use-Case
POST	`/api/key-management/keys`	Generate Key	Create a brand-new key (PQC, classical or symmetric).
POST	`/api/key-management/keys/import`	Import Key	Register pre-existing public/private material.
POST	`/api/key-management/private-keys`	Import PKCS#12	Upload a Base64 `.p12/.pfx` bundle (private key + cert).
GET	`/api/key-management/keys`	List Keys	Enumerate all keys – secret material is never returned.
GET	`/api/key-management/keys/{kid}`	Export Key	Retrieve metadata and the public portion (if asymmetric).
PATCH	`/api/key-management/keys/{kid}`	JSON Merge-Patch	Update limits / expiry in place (RFC 7396).
POST	`/api/key-management/keys/{kid}/actions/revoke`	Revoke Key	Permanently disable a key (status = REVOKED).
POST	`/api/key-management/keys/{kid}/rotations`	Rotate Key	Immediate or scheduled rotation to a successor key.
GET	`/api/key-management/rotation-jobs/{jobId}`	Rotation Job Status	Poll long-running/scheduled rotations.
DELETE	`/api/key-management/keys/{kid}`	Remove Key	Irreversibly delete a key (use with caution).
GET	`/api/key-management/supported-algorithms`	Supported Algorithms	Discover all `kty + alg` pairs, keyOps, lifecycle status.

3. Request / Response Models

All schemas are defined in the OpenAPI document under #/components/schemas/* (build 2025-05-09).

Name	Purpose
KeyGenerationRequest	Payload for POST /keys.
KeyImportRequest	Payload for POST /keys/import.
ImportPkcs12Metadata	Payload for POST /private-keys.
KeyExportResponse	Body of GET /keys/{kid} or rotation (200).
ListKeysResponse	Body of GET /keys.
RotationRequest	Payload for POST /keys/{kid}/rotations.
RotationJobResponse	Body of GET /rotation-jobs/{jobId}.
SupportedAlgorithm	Element of GET /supported-algorithms array.

4. Generate Key — Quick Reference

POST /api/key-management/keys
Content-Type: application/json
Authorization: Bearer <JWT>

{
  "kid"      : "pqk-emlkem-768",
  "kty"      : "ML-KEM",
  "alg"      : "ML-KEM-768",
  "keyOps"   : ["encrypt", "decrypt"],
  "exportable": true,
  "expiresAt": "2035-12-31T23:59:59Z",
  "softUsageLimit": 40000,
  "maxUsageLimit" : 50000
}

Success	Meaning
201 Created	New key stored.
200 OK	Metadata of an existing key was updated (idempotent).

Lifecycle warnings are not returned here; they appear when the key is used by Secure / Secure Streaming endpoints.

5. Revocation & Rotation

5.1 Revoking a Key

POST /api/key-management/keys/{kid}/actions/revoke

204 No Content on success.
After the call, status → REVOKED and the key is cryptographically\ unusable.

5.2 Rotating a Key

POST /api/key-management/keys/{kid}/rotations

Body

{
  // execute immediately
  "newKey": {
    "kid" : "pqk-emlkem-768-v2",
    "kty" : "ML-KEM",
    "alg" : "ML-KEM-768",
    "keyOps": ["encrypt","decrypt"],
    "exportable": true
  }
}

Response	Behaviour
200 OK + `KeyExportResponse`	Rotation executed synchronously.
202 Accepted + `Location`	Job queued -- poll the URI given in the `Location` header until `RotationJobResponse.status` = `SUCCEEDED` or `FAILED`.

Key chain model

oldKey.previousKid -> (unchanged) oldKey.nextKid -> newKid newKey.previousKid -> oldKey newKey.nextKid -> null

6. Supported Algorithms Endpoint

GET /api/key-management/supported-algorithms

Returns an array of SupportedAlgorithm items:

[
  {
    "kty"    : "ML-KEM",
    "alg"    : "ML-KEM-768",
    "keyOps" : ["encrypt","decrypt"],
    "status" : "RECOMMENDED",
    "sunsetDate": null,
    "advisory": "Use ML-KEM-1024 for archival ≥ 30 years."
  },
  {
    "kty"    : "RSA",
    "alg"    : "RSA-2048",
    "keyOps" : ["encrypt","decrypt","sign","verify"],
    "status" : "LEGACY",
    "sunsetDate": "2025-12-31",
    "advisory": "Migrate to RSA-3072 or PQC KEM before sunset."
  }
]

Field	Meaning
status	`RECOMMENDED` -- safe for new deployments; `LEGACY` -- transitional.
sunsetDate	Last day for new deployments; existing data remains decryptable.
advisory	Human guidance for architects and compliance teams.

7. Error Model

All failure codes (400-5xx) use the\ RFC 7807 envelope ProblemDetails.\ Important sub-types:

HTTP Code	`type`	Typical Trigger
400	`/errors/invalid-input`	Missing fields, malformed Base64, invalid merge-patch.
404	`/errors/not-found`	`kid`/`jobId` does not exist.
409	`/errors/conflict`	Algorithm mismatch, duplicate `kid`.
413	`/errors/payload-too-large`	JSON > 5 MB or PKCS#12 > 5 MB.
500	`/errors/internal`	Unhandled keystore / crypto fault.

8. Security

All endpoints require Bearer JWT or an x-rapidapi-key\ header, as advertised in the OpenAPI\ securitySchemes.