Programmable Credential Access

A password manager built for machines: policy-gated, programmable access to secrets for humans, services, and AI agents.

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

When an AI agent needs a password, a card number, or an API key, teams face an unpleasant choice: hand the agent unfettered access to credentials, or put a human in the loop for every single request. Turnkey gives you a third option: a programmable access layer that evaluates every credential request against policies you control, inside a secure enclave that never releases plaintext unless the policy allows it.

Policies and tags are fully dynamic: update them at runtime to widen or narrow access on the fly, without re-importing anything. This solution builds on Secret Storage.

Access patterns

One policy engine supports the full spectrum of trust models:

Pattern	How it works
Unilateral agent	A session key authenticates an ephemeral agent instance as a durable agent-role user whose policy permits direct export.
Agent → human	An agent instance requests access; the export completes only after a human approves the pending activity.
Multi-agent consensus	Instances of separate agent-role users must each sign the same export before the secret is released, and only the designated recipient can decrypt it.

Key implementation decisions

Decision	What to consider	Learn more
Secret classification	Bind static properties at import time (kind, environment, requiresConsensus, …) so policies target classes of secrets instead of individual IDs.	Secret Storage
Agent identity	Model each agent type or role as a durable Turnkey user. A scoped, expiring session key authenticates each ephemeral instance of that user, making credential delegation easy to express in policy.	Sessions
Consensus requirements	Decide which secret classes need one agent role, several, or a specific combination of user tags (e.g. one browser-agent and one payment-agent).	Policy Engine
Recipient control	The export payload is encrypted to a single ephemeral public key. Decide which party generates that key. That party, and only that party, can read the secret.
Revocation	Invalidate a session key to revoke one agent instance, or delete the agent-role user to revoke every instance of that role.	Sessions

Example: multi-agent consensus for payments

Model a browser agent and a payment agent as durable Turnkey users, with session keys that authenticate their ephemeral instances. Policy requires both agent roles to approve before the enclave exports card details, and only the payment agent instance holds the decryption key. Neither instance can act alone, and the browser agent never sees the card.

Need	How Turnkey solves it
No single agent instance can exfiltrate the card	Consensus policy requires approvals from both durable agent-role users before the enclave re-encrypts the secret
Approver ≠ recipient	The payload is encrypted to the payment agent instance’s ephemeral key; the browser agent instance’s approval releases a ciphertext it cannot read
Agent instances act in parallel	Both instances sign and submit the byte-identical export request in any order. Turnkey matches them to the same activity
Every access is attributable	Each export and approval is signed with a session key and logged under the durable agent-role user

Policy: require two agent roles for credit card access

{
  "policyName": "Require two agent roles for credit card access",
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(u, u.tags.contains('browser-agent')) && approvers.any(u, u.tags.contains('payment-agent'))",
  "condition": "activity.type == 'ACTIVITY_TYPE_EXPORT_SECRETS' && secret.static_properties['requiresConsensus'] == 'true' && secret.static_properties['kind'] == 'creditCard'"
}

Implementation steps

1. Import the credential

   Import the card once, with static properties that the policy above targets. Any client with import permission can do this. Here, a backend service imports it:

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

   The payment agent instance, the intended recipient, generates an ephemeral keypair and builds the proposal. createExportSecretsProposal is a local call: it produces the canonical request body and its fingerprint, with no network round trip.

   import { generateP256KeyPair } from "@turnkey/crypto";
   
   const { publicKey, privateKey } = generateP256KeyPair();
   
   const proposal = paymentAgent.createExportSecretsProposal({
     secrets: [{ secretId }],
     targetPublicKey: publicKey,
     organizationId,
   });
   

   The proposal is plain JSON and contains no key material. Share it with co-signing agent instances over any channel.

3. Both agent instances sign and submit in parallel

   Each agent instance stamps the identical proposal body with the session key for its durable agent-role user and submits. Order doesn’t matter: the first submission creates the activity, and every subsequent identical submission counts as an approval.

   await Promise.all([
     paymentAgent.submitExportSecrets(proposal),
     browserAgent.submitExportSecrets(proposal),
   ]);
   

   Until the consensus expression is satisfied, the activity reports ACTIVITY_STATUS_CONSENSUS_NEEDED and no secret leaves the enclave.

4. Payment agent instance decrypts

   Once policy is satisfied, the enclave re-encrypts the card to the payment agent instance’s ephemeral key. Only that instance can decrypt:

   const [cardJson] = await paymentAgent.awaitExportedSecrets({
     proposal,
     embeddedPrivateKey: privateKey,
   });
   
   const card = JSON.parse(cardJson);
   

For direct human approval instead of a second agent role, skip the co-signing step: the activity stays in CONSENSUS_NEEDED until the human approves it from the dashboard or via approve_activity.

Next steps