Secret Storage

Closed beta: the Secrets API is currently in closed beta. Contact us to get onboarded.

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. Turnkey’s coordinator, database, and public API only ever see ciphertext.

How it works

Import: Turnkey mints a single-use ingress target key inside the enclave, signed by the enclave’s quorum key. Your client verifies that signature, encrypts the secret to the target key using HPKE, and submits the ciphertext. The enclave decrypts it, re-encrypts it for storage at rest under a quorum-key-derived key, and deletes the ingress key. Export: the export request carries an ephemeral P-256 target public key, and after policy evaluation approves the request, the enclave decrypts the stored secret and re-encrypts it to that key. The target 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 private half can decrypt the result. The export payload is useless to anyone else, including the approvers themselves. For a batch export, the request succeeds only if every policy evaluation returns ALLOW. A DENY, or any evaluation without an ALLOW outcome, rejects the entire batch. Turnkey 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": "activity.type == 'ACTIVITY_TYPE_EXPORT_SECRETS' && secret.static_properties['kind'] == 'creditCard'"
}

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, with the organization, secret ID, and cipher suite 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