Skip to main content

Keys & Secrets API reference

Project keys, secrets, HYOK clusters and hosts, custody transitions and the signed audit ledger.

Vault

The project's vault status: its custody mode, its active key, and the last custody change.

Any project member can read it.

  • Returns the project's custody mode, its active key, and the last custody change that completed.

Keys

The project's key-encryption key (KEK) versions.

List and read them, and rotate to a new version, which re-wraps every data key under the new KEK.

Reading keys needs a project admin or auditor; rotating needs a project admin.

  • GETList Keys/vault/keys

    Returns the project's key-encryption key (KEK) versions.

  • GETGet Key/vault/keys/{key_id}

    Returns one of the project's keys.

  • POSTRotate Key/vault/keys/{key_id}/rotate

    Creates a new version of the project's platform KEK and re-wraps every data key under it.

Secrets

Store, read, update, move, rotate and delete secret values, addressed by a /-delimited path, and list a secret's versions.

The creator owns a secret and only the owner can change it; its visibility decides who else can list and reveal it.

Revealing takes a single-use challenge, and every reveal is recorded in the audit ledger.

  • GETList Secrets/vault/secrets

    Returns a page of the secrets the caller owns or that are shared with them, in path order, without their values.

  • POSTCreate Secret/vault/secrets/{path}

    Creates a secret at path from a base64 value, with a visibility and optional metadata.

  • GETReveal Secret/vault/secrets/{path}

    Returns a secret's value, base64.

  • GETList Secret Versions/vault/secrets/{path}?op=versions

    Returns a secret's value, base64.

  • PUTUpdate Secret/vault/secrets/{path}

    Stores a new value for a secret as its next version.

  • POSTMove Secret/vault/secrets/{path}?op=move

    Creates a secret at path from a base64 value, with a visibility and optional metadata.

  • POSTRotate Secret/vault/secrets/{path}?op=rotate

    Creates a secret at path from a base64 value, with a visibility and optional metadata.

  • POSTRequest Reveal Challenge/vault/secrets/{path}?op=reveal-challenge

    Creates a secret at path from a base64 value, with a visibility and optional metadata.

  • DELETEDelete Secret/vault/secrets/{path}

    Revokes a secret at once: it can no longer be read or revealed.

HYOK Clusters & Hosts

Register the KMIP managers in your organisation and group them into clusters, which a project can attach to for hold-your-own-key custody.

These are organisation resources and need an organisation admin.

  • GETGet Summary/vault/hyok

    Returns the project's HYOK attachment for a region: the cluster it uses, the HSM model, and the key's KMIP id (keyUid).

  • POSTCreate Cluster/vault/hyok/clusters

    Groups registered hosts into a cluster.

  • GETList Clusters/vault/hyok/clusters

    Returns the organisation's HYOK clusters.

  • GETGet Cluster/vault/hyok/clusters/{cluster_id}

    Returns one HYOK cluster.

  • PATCHUpdate Cluster/vault/hyok/clusters/{cluster_id}

    Renames a cluster, moves it to another region or replaces its hosts.

  • DELETEDelete Cluster/vault/hyok/clusters/{cluster_id}

    Deletes a cluster and its host memberships.

  • POSTCreate Host/vault/hyok/hosts

    Registers a KMIP endpoint and the certificate references kibo uses to reach it.

  • GETList Hosts/vault/hyok/hosts

    Returns the organisation's HYOK hosts, newest first.

  • GETGet Host/vault/hyok/hosts/{host_id}

    Returns one HYOK host.

  • PATCHUpdate Host/vault/hyok/hosts/{host_id}

    Changes a host's label, endpoint or certificate references.

  • DELETEDelete Host/vault/hyok/hosts/{host_id}

    Deregisters a host.

Custody & Exit

Change a project's custody mode, read what your key's trust policy must name, and read the signed attestations that a project's keys were destroyed on exit.

Changing mode re-wraps every data key under the new KEK without decrypting the values.

  • GETGet Custody Trust/vault/custody-trust

    Returns the values your key's trust policy must name before kibo can use the key: the AWS principal kibo calls from and the external id it sends, and the issuer and subject of the identity kibo fed…

  • POSTStart Custody Transition/custody-mode-transition

    Changes the project's custody mode.

  • GETGet Transition Status/custody-mode-transition/{job_id}

    Returns a custody transition job's state.

  • GETList Exit Attestations/vault/exit/attestations

    Returns the signed receipts recording that the project's keys were destroyed.

  • GETGet Exit Attestation/vault/exit/attestations/{attestationId}

    Returns one signed receipt recording that a project key was destroyed.

Audit Ledger

Download the signed, hash-chained ledger of every key and custody change, have it verified server-side, and fetch the public keys that verify its signature.

Signing keys need no authentication, so anyone can check a signature.

  • GETDownload Ledger/vault/audit-ledger

    Returns the project's ledger events in sequence order, optionally limited to the range from to to.

  • POSTVerify Ledger/vault/audit-ledger/verify

    Checks the project's ledger on the server: the hash chain and every signature.

  • GETGet Signing Keys/vault/ledger-signing-key

    Returns the public keys that verify ledger signatures and exit attestations: the active key and the earlier ones, so an old signature still verifies.