# Mint, inspect, and retire signing keys

> Mint a signing key in a context, list and inspect the keys a context holds, replace one whose label is out of date, and revoke a key that should no longer sign.

By the end of this guide, you can add a signing key to a context, see what a context already holds, and take a key out of service.

A VTA holds the private half of every signing key it mints and signs on a caller’s behalf, so managing keys means managing records on the VTA rather than files on your machine. For what a key record contains, and how keys are derived, see [Keys and contexts](/products/affinidi-elements/vta/concepts/keys-and-contexts.md).

Without this, a context accumulates keys nobody can account for: minting is not idempotent, so a repeated setup script leaves duplicates behind, and a key that should have been retired keeps signing until someone removes it.

Use this guide when:

- An application needs its own signing key inside a context.

- You want to see which keys a context already holds before adding another.

- A key is being retired, replaced, or was minted by mistake.

- A key’s label no longer describes what it is used for.

You do not need this guide to replace an application’s credential, which is a separate thing from the keys it signs with; see [Rotate an application credential](/products/affinidi-elements/vta/vta-management/rotate-application-credential.md).

## Prerequisites

- 
A running VTA. See [Quickstart](/products/affinidi-elements/vta/get-started.md).

- 
pnm installed and connected to the VTA.

```bash
cargo install pnm-cli@0.45.0 --locked --registry crates-io
```

- 
Admin or Initiator access to the VTA to mint keys, and Admin access to revoke them.

- 
The ID of the context the key belongs to, from pnm contexts list.

- 
For Test 2: [Rust 1.95 or later](https://www.rust-lang.org/tools/install), and a vta-sdk client connected with an application credential for the key’s context, as in Steps 3 to 5 of [Sign application payloads without exposing your keys](/products/affinidi-elements/vta/integration-guides/provisioning-app-signing.md).

## Mint a key

Every context starts with no keys. Mint one so the applications in that context have something to sign with:

```bash
pnm --vta  keys create \
    --key-type ed25519 \
    --context  my-app \
    --label    "my-app-key-1"
```

```text
Key created:
  Key ID:          m/26'/2'/2'/0'
  Key Type:        ed25519 (classical signing)
  Derivation Path: m/26'/2'/2'/0'
  Public Key:      z6MkvZqY2CbpWQmbjuuNshtAptH8qbFaCGk3w6Jt72xBXiGi
  Status:          active
  Label:           my-app-key-1
  Created At:      2026-09-16 10:24:07 +08:00
```

The bracketed part of Key Type is the key’s quantum posture: classical signing means a quantum computer running Shor’s algorithm could break it, while ML-DSA keys show post-quantum signing. The Key ID is the derivation path, not a short opaque identifier. Give every key a --label that says what uses it: the label is the only field that will still mean something to you a year from now.

This command is not idempotent. Running it twice mints two keys, so check what a context already holds before minting into it.

## List the keys a context holds

```bash
pnm --vta  keys list --context my-app
```

Add --status active to hide keys that have already been revoked. A context with nothing in it reports No keys found.

## Inspect one key

```bash
pnm --vta  keys get "m/26'/2'/2'/0'"
```

```text
Key ID:          m/26'/2'/2'/0'
Key Type:        ed25519 (classical signing)
Derivation Path: m/26'/2'/2'/0'
Public Key:      z6MkvZqY2CbpWQmbjuuNshtAptH8qbFaCGk3w6Jt72xBXiGi
Status:          active
Label:           my-app-key-1
Created At:      2026-09-16 10:24:07 +08:00
Updated At:      2026-09-16 10:24:07 +08:00
```

Quote the key ID in your shell. It contains ' characters, which an unquoted shell will try to interpret.

Public Key is the value a third party needs to check a signature this key produced. It is safe to share. A signature from the VTA’s sign operation covers a domain-separated form of the payload, so the verifier checks it over that same input. See [Sign a payload](/products/affinidi-elements/vta/integration-guides/provisioning-app-signing.md#sign-a-payload). The private half stays on the VTA unless an admin with key-export rights exports it.

## Replace a key whose label is out of date

A key’s label is set when the key is minted. To give a key a label that matches its current use, mint a new key with that label in the same context, as in [Mint a key](#mint-a-key), move your application to the new key, then revoke the old one as shown below.

## Retire a key

Revoking marks the key as no longer usable for signing. The record stays, so the key ID keeps resolving and your audit trail still makes sense:

```bash
pnm --vta  keys revoke "m/26'/2'/2'/0'"
```

```text
Key revoked:
  Key ID:     m/26'/2'/2'/0'
  Status:     revoked
  Updated At: 2026-09-16 11:02:41 +08:00
```

Mint the replacement and move the application onto it before revoking, rather than after. Signatures the key produced in the past remain verifiable against its public key; revoking stops new ones.

## Confirm

### Test 1: the new key is listed as active

```bash
pnm --vta  keys list --context my-app --status active
```

The key from “Mint a key” appears, with the label you gave it.

### Test 2: the key signs

  About vta-sdk

The code in this guide uses [vta-sdk](https://crates.io/crates/vta-sdk), the Rust client library for the VTA, published on crates.io with API documentation on [docs.rs](https://docs.rs/vta-sdk). pnm is built on the same crate. From another language, connect through the MCP bridge, or send signed Trust Task documents to the VTA’s HTTPS endpoint yourself, as described in [Which client to use for your language](/products/affinidi-elements/vta/concepts/request-model.md#which-client-to-use-for-your-language).

Sign a short payload from the VTA SDK, which builds and signs the [Trust Task](/products/affinidi-elements/vta/concepts/request-model.md) document a sign request needs. pnm has no sign command, so use a client connected with an application credential scoped to the key’s context, as in Steps 3 to 5 of [Sign application payloads without exposing your keys](/products/affinidi-elements/vta/integration-guides/provisioning-app-signing.md):

```rust
use vta_sdk::protocols::key_management::sign::SignAlgorithm;

let result = client
    .sign("m/26'/2'/2'/0'", b"hello", SignAlgorithm::EdDSA)
    .await?;
println!("{}", result.signature);
```

A base64url-encoded signature comes back, produced without the private key leaving the VTA.

### Test 3: a revoked key no longer signs

Re-run Test 2 against a key you revoked. The VTA refuses it with cannot sign with a revoked key, which confirms the revocation took effect rather than only changing a displayed status.

## Troubleshooting

| Symptom | Likely cause | Fix |
| pnm keys create fails with keys/create denied: <did> does not carry the key-mint capability | Your session’s role lacks the key-mint capability, which the Admin and Initiator roles carry by default. An ACL entry can be narrowed to leave it out. | Run pnm auth status to see the identity you are connected as, then use an Admin or Initiator credential. |
| Two keys with the same label in one context | keys create is not idempotent, so a setup script ran twice. | Revoke the duplicate, then list the context to confirm one active key remains. |
| The shell reports a quoting error on a key ID | The ID contains ' characters and was passed unquoted. | Wrap the key ID in double quotes: "m/26'/2'/2'/0'". |
| A revoked key still appears in pnm keys list | Revocation sets the status rather than deleting the record, so the audit trail stays intact. | Add --status active to list only usable keys. |

## Next steps

  [Sign application payloads without exposing your keys](/products/affinidi-elements/vta/integration-guides/provisioning-app-signing.md): give an application its own identity and have it sign with a key you minted here.

  [Keys and contexts](/products/affinidi-elements/vta/concepts/keys-and-contexts.md): how keys derive from one master seed and why contexts isolate them.

  [Grant and revoke access](/products/affinidi-elements/vta/vta-management/acl-management.md): control which DIDs can reach the keys in a context.
