> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turnkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Turnkey is wallet infrastructure: create and manage crypto wallets, sign transactions, and enforce policy-based access controls. Best-fit uses: embedded consumer wallets (email/passkey/social auth, no seed phrases), automated onchain operations with server-side wallets, AI agent wallets with policy-scoped signing, enterprise key management, and verifiable off-chain workloads on Turnkey Verifiable Cloud (TVC).
> Every API call is a JSON POST to https://api.turnkey.com signed with a P-256 API key; create an organization and key self-serve at https://app.turnkey.com.
> Key Turnkey developer resources: API reference (https://docs.turnkey.com/api-reference/overview/intro.md), OpenAPI spec (https://docs.turnkey.com/public_api.swagger.json), authentication (https://docs.turnkey.com/features/authentication/overview.md), webhooks (https://docs.turnkey.com/features/webhooks/overview.md), MCP server for docs search (https://docs.turnkey.com/mcp), skill for building with Turnkey (https://docs.turnkey.com/skill.md), agent skills for operating an organization (https://docs.turnkey.com/get-started/ai-skills.md), CLI (https://docs.turnkey.com/sdks/cli.md), SDK reference (https://docs.turnkey.com/sdks/introduction.md), full docs content (https://docs.turnkey.com/llms-full.txt).

# Operator keys

> Self-hosted and Turnkey-hosted TVC operator keys: where each private key lives, who controls it, and how it is created and used.

Every [operator](https://docs.turnkey.com/features/verifiable-cloud/overview.md#operators) in a [manifest set or share set](https://docs.turnkey.com/features/verifiable-cloud/manifest-sets-and-share-sets.md) is identified by a pair of P-256 public keys: one for signing manifest approvals and one for encryption, used to receive and re-encrypt Quorum Key shares. The private keys can be either self-hosted or Turnkey-hosted. This page describes each option so you can pick the right custody model for each operator.

## Compare the options

| | Self-hosted: YubiKey | Self-hosted: local key file | Turnkey-hosted |
| :- | :- | :- | :- |
| Private key lives in | PIV slots on a hardware token | A plaintext seed file on the operator's machine | Two wallet accounts in your Turnkey organization |
| Who controls it | The holder of the YubiKey | Whoever can access the file | Your organization, through Turnkey's user, API key, and [policy](https://docs.turnkey.com/features/policies/overview.md) model |
| Where signing and decryption happen | On the YubiKey, after a PIN and a touch | On the operator's machine | Inside Turnkey's enclaves, via Turnkey activities |
| Created by | `ykman` on the device, then registered with `tvc` | `tvc login`, locally | `tvc operator create`, with keys generated inside Turnkey's enclaves |
| Registered with Turnkey | When an operator set is posted with `newOperators` | When an operator set is posted with `newOperators` | By the [`create_tvc_operator`](https://docs.turnkey.com/api-reference/activities/create-tvc-operator) activity |

For production operators, use a YubiKey or a Turnkey-hosted operator. A local key file is a plaintext seed, so keep it to development, or to CI pipelines where the seed is injected from a secrets manager through `TVC_OPERATOR_SEED` and never written to disk.

A manifest set can include both self-hosted and Turnkey-hosted operators. A share set must be all self-hosted or all Turnkey-hosted.

The [`list_tvc_operators`](https://docs.turnkey.com/api-reference/queries/list-tvc-operators) query lists the operators registered in your organization.

## Self-hosted keys

Self-hosted operators keep their private keys with you. Turnkey learns only the public keys, when the operator is included in an operator set's `newOperators` at app creation, and every signature and decryption happens on your hardware.

### YubiKey

A YubiKey operator keeps the operator's two private keys, the signing key and the encryption key, in the token's PIV application, generated on the device so they can never be exported. Signing and decryption happen on the YubiKey and require the PIV PIN and a physical touch every time.

| PIV slot | Purpose | Requirements |
| :- | :- | :- |
| `9c` | Sign manifest approvals | P-256, generated on the device, PIN policy `always`, touch policy `always` |
| `9d` | Decrypt and re-encrypt Quorum Key shares | P-256, generated on the device, PIN policy `always`, touch policy `always` |

`tvc` only uses operations the PIV PIN unlocks: signing and key agreement with existing keys. It never holds the PIV management key, so it cannot generate, import, or delete keys or certificates on the device. Those changes are made with [YubiKey Manager (`ykman`)](https://docs.yubico.com/software/yubikey/tools/ykman/) commands you run yourself, so you can audit exactly what touches the device.

**Prerequisites.** YubiKey firmware 5.3 or later (check with `ykman info`), the `ykman` CLI, and a current `tvc` installation. The examples assume one YubiKey is connected; with several, unplug the others or pass `--serial <SERIAL>`.

**1. Harden PIV access**

Optional for an already-hardened device, but recommended before generating operator keys. Each command prompts for the current and replacement credential.

```sh theme={"system"}
ykman piv access change-pin
ykman piv access change-puk
ykman piv access change-management-key --generate --protect
```

`--protect` stores the generated management key on the YubiKey behind the PIN, so later `ykman` administrative operations can authorize with a PIN prompt. `tvc` never reads or uses this key.

**2. Generate the operator keys**

Generate both private keys on the device with the policies TVC requires:

```sh theme={"system"}
ykman piv keys generate \
  --algorithm eccp256 \
  --pin-policy always \
  --touch-policy always \
  9c - >/dev/null

ykman piv keys generate \
  --algorithm eccp256 \
  --pin-policy always \
  --touch-policy always \
  9d - >/dev/null
```

The printed public keys can be discarded; the next step reads them back from device metadata. Algorithm, origin, and policies can't be corrected after the fact. If `tvc` later rejects a slot, regenerate it with the exact options above, but never regenerate a slot whose key is already in use as an operator.

**3. Create and import the certificates**

QuorumOS expects each slot to carry a self-signed certificate with subject `CN=QuorumOS`. Create them with `tvc`, which prompts for the PIN and one touch per slot, then import them with `ykman`:

```sh theme={"system"}
tvc yubikey create-certs

ykman piv certificates import --verify 9c tvc-yubikey-<SERIAL>-signing.pem
ykman piv certificates import --verify 9d tvc-yubikey-<SERIAL>-key-agreement.pem
```

`create-certs` writes the two PEM files to the current directory and doesn't modify the device. `--verify` proves each certificate matches the private key in its slot. The PEM files hold public certificates only, so they're safe to keep for auditing.

**4. Register the YubiKey with tvc**

Cache the device's operator public keys in the local `tvc` configuration. This needs neither the PIN nor a touch:

```sh theme={"system"}
tvc keys refresh-yubikey --serial <SERIAL>
```

The command prints the canonical hexadecimal serial that later `tvc` commands expect.

**5. Add the operator to an organization**

With the target organization active, create an operator record that points at the registered serial. `--default` makes YubiKey the organization's default operator kind, so commands pick it without `--serial` when it's the only one:

```sh theme={"system"}
tvc operator create --kind yubikey --serial <SERIAL> --default
```

This step is local: it uses the cached public keys and doesn't contact Turnkey or modify the device. As with a local key file, Turnkey learns the public keys when the operator is included in an operator set's `newOperators` at app creation. You can also pick **YubiKey** instead of **Local key file** when `tvc login` sets up a new organization.

**Approve manifests.** Pass the serial to sign with the `9c` key. The CLI prompts for the PIN and waits for a touch:

```bash theme={"system"}
tvc deploy approve \
  --deploy-id <DEPLOYMENT_UUID> \
  --operator-id <OPERATOR_UUID> \
  --serial <SERIAL>
```

**Hold Quorum Key shares.** YubiKey operators follow the same local share lifecycle as a [local key file](#local-key-file). The `9d` key decrypts the share during re-encryption:

```bash theme={"system"}
tvc keys re-encrypt-local-share \
  --quorum-key-metadata <quorum-key-metadata.json> \
  --provision-bundle <provision-bundle.json> \
  --serial <SERIAL>
```

**Retire a YubiKey locally.** After removing the operator from every local organization profile that references it, forget the device with `tvc yubikey unregister --serial <SERIAL>`. This only edits the local configuration. The keys stay on the device, and the operator remains valid for any organization that still trusts its public keys. Remove it from a Turnkey operator set by creating a new set.

> [!TIP]
>
> Common errors: "no YubiKey is connected" means the reader can't see the device, so reinsert it and check `ykman info`. "Metadata is unavailable" means the firmware is older than 5.3. A rejected PIN should be fixed with the PUK before the retry counter runs out. A signing timeout means the device blinked and wasn't touched in time.

### Local key file

`tvc login` generates a 32-byte master seed on your machine. Both the signing key and the encryption key are derived from that seed following the [QOS key set](https://github.com/tkhq/qos/blob/main/src/qos_p256/SPEC.md) specification. The seed is written as JSON to:

```
~/.config/turnkey/orgs/<alias>/operator.json
```

The seed never leaves the file unless you move it. Turnkey learns only the public keys, which the CLI auto-populates into the `newOperators` field when you run `tvc app init`, or which you paste into the dashboard when creating an app there.

> [!NOTE]
>
> The seed is stored unencrypted. The CLI writes the file with owner-only permissions, so its protection is the operating system's access control and whatever disk encryption the machine has. Anyone who can read the file can act as that operator.

**Back it up.** A lost local key means a lost operator. If that operator was needed to meet a threshold, you'll need to create a new operator set and a new app. `tvc login` offers to back the key up during onboarding, and you can do it any time:

```bash theme={"system"}
tvc keys backup-operator-key --output <PATH>
```

The backup is a byte-for-byte copy of `operator.json`, so it holds the same plaintext seed as the original.

**Approve manifests.** With the organization active, the CLI reads the key from the file automatically:

```bash theme={"system"}
tvc deploy approve \
  --deploy-id <DEPLOYMENT_UUID> \
  --operator-id <OPERATOR_UUID>
```

To sign from a pipeline or from a machine that hasn't run `tvc login`, pass the seed explicitly with `--operator-seed-path <FILE>` (a file containing the raw hex seed) or `--operator-seed <HEX>`. The two flags are mutually exclusive.

Add `--skip-post` to sign without contacting the API, for example on an air-gapped machine. The CLI writes the approval JSON to stdout or to `--approval-out <PATH>`. There is no CLI command to submit a saved approval; post it with the [`create_tvc_manifest_approvals`](https://docs.turnkey.com/api-reference/activities/create-tvc-manifest-approvals) activity using the manifest ID, operator ID, and hex-encoded signature.

**Hold Quorum Key shares.** Local operators can be share set members too, but the share lifecycle runs on your machine rather than through Turnkey:

1. `tvc keys generate-local-quorum-key` generates a Quorum Key, splits it with Shamir's Secret Sharing, and encrypts each share to an operator's encryption key.
2. When an enclave boots, `tvc keys re-encrypt-local-share` verifies the enclave's attestation and manifest approvals, then re-encrypts your share to the enclave's Ephemeral Key.
3. `tvc deploy post-share` submits the re-encrypted share.

Each step accepts the same `--operator-seed` and `--operator-seed-path` flags as `deploy approve`. Run `tvc keys init-local-quorum-key` to generate a template configuration for step 1.

## Turnkey-hosted keys

A Turnkey-hosted operator keeps its keys in two P-256 wallet accounts in your Turnkey organization. `tvc operator create` calls the [`create_tvc_operator`](https://docs.turnkey.com/api-reference/activities/create-tvc-operator) activity, which creates a wallet named `tvc-wallet` (or reuses one you pass with `--wallet-id`) and derives two accounts under a base path. The default base path is `m/5527107'/0'/0'`, where `5527107` is the ASCII bytes of `TVC`. Turnkey appends `/0` for the encryption account and `/1` for the signing account.

```bash theme={"system"}
tvc operator create --name <OPERATOR_NAME>
```

The activity returns the operator ID, the wallet ID, and both public keys. The CLI saves them to the active organization's local profile so later commands can find the operator by ID. To create more than one hosted operator in the same wallet, give each a distinct `--account-path`.

**Who controls the key.** The private keys never leave Turnkey's enclaves, and they are never returned to the CLI. Every use of a hosted operator is a Turnkey activity submitted with your API key, so it is subject to the same controls as any other activity in your organization: the submitting user's permissions, [policies](https://docs.turnkey.com/features/policies/overview.md), consensus requirements, and the activity log. The relevant activity types are `ACTIVITY_TYPE_SIGN_RAW_PAYLOAD` for approvals and `ACTIVITY_TYPE_RE_ENCRYPT_TVC_QUORUM_KEY_SHARE` for share provisioning.

**Approve manifests.** The same command as a local operator. The CLI recognizes the operator ID as a hosted operator and signs the approval through the [`sign_raw_payload`](https://docs.turnkey.com/api-reference/activities/sign-raw-payload) activity instead of a local key:

```bash theme={"system"}
tvc deploy approve \
  --deploy-id <DEPLOYMENT_UUID> \
  --operator-id <OPERATOR_UUID>
```

Offline approval with `--skip-post` is not available for hosted operators, since signing requires the API.

**Hold Quorum Key shares.** Hosted operators have a shorter share lifecycle because Turnkey holds the encrypted shares:

1. `tvc keys create-quorum-key --threshold <N> --operator-ids <IDS>` creates the Quorum Key inside Turnkey's enclaves with one share encrypted to each hosted operator.
2. `tvc deploy provision --deploy-id <ID> --operator-id <ID>` verifies the enclave's attestation and approvals, then calls the [`re_encrypt_tvc_quorum_key_share`](https://docs.turnkey.com/api-reference/activities/re-encrypt-tvc-quorum-key-share) activity to re-encrypt that operator's share to the enclave's Ephemeral Key.

The [manifest sets and share sets](https://docs.turnkey.com/features/verifiable-cloud/manifest-sets-and-share-sets.md#worked-example) page walks through a full hosted setup.

## See also

* [Manifest sets and share sets](https://docs.turnkey.com/features/verifiable-cloud/manifest-sets-and-share-sets.md) for how operators are grouped and what their thresholds protect
* [Quickstart](https://docs.turnkey.com/features/verifiable-cloud/quickstart.md) for the local-key flow end to end
* [`create_tvc_operator`](https://docs.turnkey.com/api-reference/activities/create-tvc-operator) and [`list_tvc_operators`](https://docs.turnkey.com/api-reference/queries/list-tvc-operators) API references


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.