Secret storage

Turnkey Secrets lets you store arbitrary sensitive data (passwords, credit card details, API keys, SSNs) encrypted end-to-end between your client and Turnkey’s secure enclaves. The policy engine evaluates every export, so you control exactly who can retrieve a secret, under what conditions, and with how many approvals. We designed the secret storage API for flexibility and programmability. Plaintext only ever exists inside the enclave and on the client that imported or exported it.

How it works

The Secrets methods use the same enclave secure-channel pattern as wallet import and wallet export. Every transfer is HPKE-encrypted to a single-use target key, so plaintext appears only inside the enclave and on the client holding the matching private key. See Enclave secure channels for the canonical protocol details. What is specific to Secrets:

Import: your client encrypts the secret to a single-use ingress target key minted inside the enclave and submits only ciphertext. The enclave re-encrypts it for storage at rest and deletes the ingress key.
Export: the export request carries an ephemeral P-256 target public key. After policy evaluation approves the request, the enclave re-encrypts the secret to that key. The recipient key is fully configurable: it can belong to the requester, to another agent or service, or to a party that isn’t an approver at all. Only the holder of the matching private key can decrypt the result; the payload is useless to anyone else, including the approvers themselves.
Batch export is all-or-nothing: the request succeeds only if every policy evaluation returns ALLOW. A DENY, or any evaluation without an ALLOW outcome, rejects the entire batch. Turnkey fails closed and never exports part of a batch.

Static properties

Secrets are created with optional static properties: string key-value pairs that are immutably bound to the secret and visible to the policy engine. They let you write export policies against classes of secrets instead of individual IDs:

{
  "policyName": "Only the payments agent can export credit cards",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(u, u.tags.contains('payment-agent'))",
  "condition": "secret.static_properties['kind'] == 'creditCard' && activity.type == 'ACTIVITY_TYPE_EXPORT_SECRETS'"
}

Importing a secret

The importSecret method in @turnkey/sdk-server and @turnkey/core handles the full flow. It initializes the ingress key, verifies the enclave signature, encrypts the secret, and submits the ciphertext:

const secretId = await turnkey.apiClient().importSecret({
  plaintext: JSON.stringify({ number: "4242...", exp: "11/29", cvv: "123" }),
  name: "corporateVisa",
  staticProperties: {
    kind: "creditCard",
    requiresConsensus: "true",
  },
});

For sensitive material you want wiped from memory after encryption, pass a Uint8Array instead of a string. The SDK zeroizes the buffer after it produces the ciphertext. Under the hood this calls init_import_secrets and import_secrets.

Exporting a secret

exportSecret generates the ephemeral keypair, submits the export activity, decrypts the result, and zeroizes the key. It is a single call when policy allows the caller to export unilaterally:

const plaintext = await turnkey.apiClient().exportSecret({
  secretId,
});

If the export requires additional approvals, exportSecret throws a consensus-needed error. For multi-party flows, including multiple agent instances that co-sign the same export with session keys, use the proposal SDK helpers described in Programmable credential access.

Listing secrets

list_secrets returns metadata: IDs, names, static properties, and creation timestamps:

const { secrets } = await turnkey.apiClient().listSecrets({});

Multi-party approval

Because export is an activity, it composes with everything the policy engine supports: consensus across durable users, tag-based approver requirements, and root quorum. Model browser and payment agent roles as separate Turnkey users, then use session keys to authenticate their ephemeral instances. Policy can require both roles to approve before a credit card leaves the enclave, while the payload stays encrypted to only one instance. This makes credential delegation easy to model without treating each ephemeral agent instance as a separate user.

Security model

Turnkey is a signing and encryption platform running inside secure enclaves, originally built to secure billions of dollars in digital assets. Secret storage is built from the same primitives:

End-to-end encryption: plaintext exists only in enclave memory and on your client. Transport in both directions uses HPKE to single-use P-256 target keys.
Authenticated storage: at-rest ciphertext is AES-256-GCM under a per-secret key derived from the enclave quorum key. The organization, secret ID, and cipher suite are bound into the authenticated data, so no one can substitute ciphertext across secrets or organizations.
Signed provenance: the enclave quorum key signs every stored secret and ingress key. Enclaves refuse anything they didn’t produce.
Quantum resistant internally, agile in transit: secrets rest under AES-256-GCM, a quantum resistant cipher. The transport cipher suite is a field in import and export requests, designed to be extended over time, so Turnkey can adopt new transport protocols as they mature.
Forward secrecy: ingress and egress target keys are single-use. Compromising one exposes at most one payload.
Full auditability: every import, export, and approval is an activity that is attributed to the authenticating credential, logged, and queryable.

Get started

Features

Reference

How it works

Static properties

Importing a secret

Exporting a secret

Listing secrets

Multi-party approval

Security model

Next steps

​How it works

​Static properties

​Importing a secret

​Exporting a secret

​Listing secrets

​Multi-party approval

​Security model

​Next steps

How it works

Static properties

Importing a secret

Exporting a secret

Listing secrets

Multi-party approval

Security model

Next steps