High Security API Key Storage

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

An exchange API key that can place orders, cancel orders, or move funds is a direct line to your balance sheet. It usually sits in an environment variable, a config file, or a vault that decrypts inside the infrastructure you are trying to protect. An attacker who compromises that infrastructure gets the key too. Turnkey removes the plaintext from your infrastructure entirely. The credential lives encrypted inside a secure enclave, and every retrieval is evaluated by the policy engine before the enclave releases anything. You decide which service identities can retrieve which keys, under what conditions, and with how many approvals. This solution builds on Secret Storage. Typical credentials this pattern protects:

Exchange and EMS API keys for trading operations (REST and WebSocket)
Long-lived JWTs and bearer tokens with broad authority
OAuth refresh tokens for backend services
Service account credentials for third party platforms

Why not a traditional secrets vault?

	Vault in your infrastructure	Turnkey
Where plaintext exists	Decrypted inside your infrastructure, where a vault admin or a compromised host can read it	Only inside the enclave and on the single authorized recipient
Access control	Enforced by software you operate	Enforced by the policy engine inside the enclave, independent of your infrastructure
Multi-party approval	Bolted on, if available	Native consensus: require m-of-n approvals before a key is released
Who can read a released secret	Anyone who sees the response	Only the holder of the ephemeral key the payload is encrypted to, which approvers cannot read
Audit trail	Vault logs you maintain	Every retrieval and approval is a signed, attributable Turnkey activity

Key implementation decisions

Decision	What to consider	Learn more
Key classification	Bind static properties at import time (`exchange`, `permissions`, `environment`, …) so policies target classes of keys, such as all withdrawal-capable keys, instead of individual IDs.	Secret Storage
Service identity	Model each trading service or environment as a Turnkey user with its own API key or session keys, so retrieval permission is scoped per service.	Sessions
Approval requirements	Trade-only keys can allow unilateral retrieval by the trading service. Withdrawal-capable or production keys can require human or multi-party approval.	Policy Engine
Recipient control	The export payload is encrypted to a single ephemeral public key, so only the service that generated it can read the credential, even when other parties approve.
Rotation and revocation	Rotate by importing the new key and deleting the old one. Revoke a service’s access instantly by updating policy or removing its credentials.

Example: exchange trading key for a trading firm

A trading firm holds a long-lived JWT for an execution management system that authorizes placing and canceling orders on crypto exchanges. The plaintext should never exist in the firm’s own infrastructure.

Need	How Turnkey solves it
Plaintext never lives in the firm’s infrastructure	The firm imports the JWT once over an end-to-end encrypted channel, and it stays inside the enclave. Retrieval re-encrypts it to a single ephemeral key
Only the trading service can retrieve it	Policy scopes retrieval of `kind == 'exchangeApiKey'` secrets to the trading service user
High-risk keys need oversight	A consensus policy requires human approval before any withdrawal-capable key is released
Every access is attributable	Each retrieval and approval is a signed activity, logged and queryable

Policy: scope retrieval to the trading service

{
  "policyName": "Trading service can retrieve trade-only exchange keys",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(u, u.id == '<TRADING_SERVICE_USER_ID>')",
  "condition": "activity.type == 'ACTIVITY_TYPE_EXPORT_SECRETS' && secret.static_properties['kind'] == 'exchangeApiKey' && secret.static_properties['permissions'] == 'trade'"
}

Implementation steps

Import the API key

Import the credential once, with static properties the policies above target. The client encrypts the plaintext to the enclave. Turnkey’s API and database only ever see ciphertext:

const secretId = await turnkey.apiClient().importSecret({
  plaintext: emsJwt,
  name: "ems-trading-key",
  staticProperties: {
    kind: "exchangeApiKey",
    permissions: "trade",
    environment: "production",
  },
});

You can now delete the plaintext from wherever it existed before.

Retrieve at runtime

The trading service authenticates with its own credentials and retrieves the key when it boots or opens a session. exportSecret generates the ephemeral keypair, submits the export activity, decrypts the result, and zeroizes the key:

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

// Use the JWT for REST or WebSocket calls, keep it in memory only

Require approval for high-risk keys

For withdrawal-capable keys, add a consensus policy so no service can retrieve them alone:

{
  "policyName": "Withdrawal-capable keys require a human approver",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(u, u.id == '<TRADING_SERVICE_USER_ID>') && approvers.any(u, u.tags.contains('risk-admin'))",
  "condition": "activity.type == 'ACTIVITY_TYPE_EXPORT_SECRETS' && secret.static_properties['kind'] == 'exchangeApiKey' && secret.static_properties['permissions'] == 'withdraw'"
}

The export stays in ACTIVITY_STATUS_CONSENSUS_NEEDED until a risk admin approves it from the dashboard or via approve_activity, and the released payload is still readable only by the trading service.

Rotate and revoke

Rotate by importing the replacement key and deleting the old secret. Revoke a service by invalidating its session keys or removing its user. Policy changes take effect immediately, with no re-encryption or re-import of the stored keys.

Overview

Embedded Wallets

Company Wallets

Key Management

Cookbooks

High Security API Key Storage

Why not a traditional secrets vault?

Key implementation decisions

Example: exchange trading key for a trading firm

Policy: scope retrieval to the trading service

Implementation steps

Next steps

​Why not a traditional secrets vault?

​Key implementation decisions

​Example: exchange trading key for a trading firm

​Policy: scope retrieval to the trading service

​Implementation steps

​Next steps

Why not a traditional secrets vault?

Key implementation decisions

Example: exchange trading key for a trading firm

Policy: scope retrieval to the trading service

Implementation steps

Next steps