---
name: turnkey
description: Use when building embedded wallets for consumer apps, automating
  server-side signing for company operations, provisioning AI agents with
  signing authority, managing high-value cryptographic keys, or deploying
  verifiable workloads. Reach for Turnkey when you need non-custodial wallet
  infrastructure, policy-scoped access controls, multi-chain signing, or secure
  key management in hardware-backed enclaves.
metadata:
  mintlify-proj: turnkey
  version: "1.0"
---

# Turnkey Skill

## Product summary

Turnkey is wallet infrastructure for developers: secure key management, transaction signing, and programmable access controls built on hardware-backed secure enclaves. Every signing operation happens inside Trusted Execution Environments (TEEs)—private keys never leave the enclave and are never exposed to your application or team.

Turnkey is API-first. All operations are JSON POST requests to `https://api.turnkey.com`, signed with a P-256 API key or passkey. Use the REST API directly, or choose from SDKs for TypeScript, React, React Native, Swift, Kotlin, and Flutter.

**Key files and concepts:**
- Organization: top-level entity containing users, wallets, and policies
- Sub-organization: fully isolated org for end users or tenants (parent has read-only access)
- User: resource that submits activities via API key, passkey, or email/phone
- Wallet: HD wallet (seed phrase) generating multiple accounts across chains
- Policy: rule controlling who can sign what, under what conditions (deny-by-default)
- Activity: any action submitted to Turnkey (sign transaction, create user, update policy)

**Primary docs:** https://docs.turnkey.com

## When to use

Reach for Turnkey when you need to:

- **Embed wallets in consumer apps** — Non-custodial wallets users access with email, passkeys, phone, or social login. No seed phrases or browser extensions.
- **Automate server-side signing** — Custodial wallets for payouts, treasury operations, payment orchestration, and smart contract management.
- **Give AI agents signing authority** — Provision agents with wallets and constrain them with policies: spending caps, destination allowlists, approval flows.
- **Secure high-value keys** — Hardware-backed storage for signing keys, encryption keys, and secrets with programmable access controls.
- **Sign across multiple chains** — EVM, Solana, Bitcoin, Cosmos, Tron, Sui, Aptos, and 20+ other networks with a single API.
- **Enforce access controls** — Role-based policies, multi-party approval, and consensus-based signing for sensitive operations.

Do not use Turnkey for: local key storage, password management, or non-cryptographic operations.

## Quick reference

### Core API endpoints

| Operation | Endpoint | Use case |
|-----------|----------|----------|
| Create wallet | `POST /public/v1/submit/create_wallet` | Generate new HD wallet |
| Sign transaction | `POST /public/v1/submit/sign_transaction` | Sign EVM, Solana, or other chain txs |
| Broadcast transaction | `POST /public/v1/submit/broadcast_evm_transaction` | Submit signed tx to network |
| Create user | `POST /public/v1/submit/create_users` | Add team member or service account |
| Create policy | `POST /public/v1/submit/create_policy` | Define access control rules |
| Get wallet | `POST /public/v1/query/get_wallet` | Fetch wallet details |
| List wallets | `POST /public/v1/query/list_wallets` | Enumerate wallets in org |
| Get activity | `POST /public/v1/query/get_activity` | Check status of submitted activity |

### Authentication methods

| Method | Use case | Credential type |
|--------|----------|-----------------|
| API key | Server-to-server, backend automation | P-256 keypair (public + private) |
| Passkey | User login, sensitive operations | WebAuthn credential |
| Email OTP | Passwordless user signup/login | One-time code sent to email |
| SMS OTP | Phone-based verification | One-time code sent to SMS |
| Social login | Quick onboarding (Google, Apple, Discord, etc.) | OAuth provider token |
| Wallet login | Web3 users (Sign-In With Ethereum/Solana) | Signed message from external wallet |

### Wallet configuration

| Parameter | Options | Default |
|-----------|---------|---------|
| Curve | `CURVE_SECP256K1`, `CURVE_ED25519` | SECP256K1 |
| Address format | `ADDRESS_FORMAT_ETHEREUM`, `ADDRESS_FORMAT_SOLANA`, `ADDRESS_FORMAT_BITCOIN_*`, etc. | Chain-specific |
| Mnemonic length | 12, 15, 18, 21, 24 words | 12 words |
| Derivation path | BIP-32 format (e.g., `m/44'/60'/0'/0/0`) | Chain-specific standard |

### Common policy conditions

```json
{
  "effect": "EFFECT_ALLOW",
  "consensus": "approvers.any(user, user.id == '<USER_ID>')",
  "condition": "eth.tx.to == '<ALLOWED_ADDRESS>' && eth.tx.value <= 1000000000000000000"
}
```

- `eth.tx.to` — recipient address
- `eth.tx.value` — transaction value in wei
- `eth.tx.data` — calldata
- `sol.tx.accounts[*].address` — Solana account addresses
- `approvers.any()` — consensus requirement

## Decision guidance

### When to use embedded wallets vs. company wallets

| Scenario | Embedded Wallets | Company Wallets |
|----------|------------------|-----------------|
| End users own their wallets | ✓ | ✗ |
| Your app controls signing | ✗ | ✓ |
| Hybrid (user + app approval) | ✓ | ✓ |
| Per-user isolation needed | ✓ (sub-orgs) | ✓ (sub-orgs) |
| Automated backend signing | ✗ | ✓ |
| AI agent signing | ✓ | ✓ |

### When to use API key vs. passkey stamping

| Scenario | API key | Passkey |
|----------|---------|---------|
| Server-to-server requests | ✓ | ✗ |
| User-initiated signing | ✗ | ✓ |
| Automated workflows | ✓ | ✗ |
| Sensitive operations requiring user approval | ✗ | ✓ |
| Mobile/native apps | ✗ | ✓ |

### When to use policies vs. root quorum

| Scenario | Policy | Root quorum |
|----------|--------|-------------|
| Granular role-based access | ✓ | ✗ |
| Spending limits, address allowlists | ✓ | ✗ |
| Multi-party approval for sensitive ops | ✓ | ✓ |
| Bypass all controls (emergency) | ✗ | ✓ |
| Scoped service account access | ✓ | ✗ |

## Workflow

### Typical task: Set up embedded wallet with email auth

1. **Create organization** — Sign up at https://app.turnkey.com/dashboard/auth/initial
2. **Get organization ID** — Copy from user dropdown (top right)
3. **Create API key** — Navigate to My Profile → Create an API key → save public + private keys
4. **Enable Auth Proxy** — Dashboard → Embedded Wallets → Configuration → enable Auth Proxy
5. **Configure auth methods** — Enable email OTP and/or passkeys; save Auth Proxy Config ID
6. **Install SDK** — `npm install @turnkey/react-wallet-kit` (or TypeScript/React Native equivalent)
7. **Initialize client** — Pass organization ID and Auth Proxy Config ID to TurnkeyProvider
8. **Add auth UI** — Use pre-built components or call `handleLogin()` / `handleSignup()`
9. **Create wallet** — Call `createWallet()` after user authenticates
10. **Sign transaction** — Call `signTransaction()` with wallet account address and unsigned tx
11. **Broadcast** — Use `broadcastEVMTransaction()` or submit to network directly
12. **Verify** — Check activity status with `getActivity(activityId)`

### Typical task: Set up company wallet with role-based access

1. **Create organization** — Sign up at https://app.turnkey.com
2. **Create wallet** — API call or dashboard: `createWallet()` with desired chains
3. **Create users** — Add team members or service accounts via `createUsers()`
4. **Tag users** — Assign tags (e.g., `treasury-ops`, `deployer`) via `createUserTag()`
5. **Define policies** — Create policies scoping each tag to allowed operations (addresses, values, chains)
6. **Test policies** — Sign test transactions with each user; verify allow/deny outcomes
7. **Set up API keys** — Generate API keys for service accounts; store securely
8. **Integrate backend** — Use server SDK (TypeScript, Go, Python, Ruby, Rust) to sign transactions
9. **Monitor activities** — Query activity log to audit who signed what and when
10. **Adjust policies** — Update policies as roles and permissions evolve

### Typical task: Provision AI agent with signing authority

1. **Create sub-organization** — Call `createSubOrganization()` with agent as root user
2. **Create wallet** — Generate wallet in sub-org for agent to control
3. **Create policies** — Define strict policies: spending caps, contract allowlists, function selectors
4. **Create agent user** — Add agent as non-root user with API key credential
5. **Scope API key** — Attach policies to agent user limiting what it can sign
6. **Test signing** — Agent calls `signTransaction()` with constrained payloads
7. **Monitor** — Query activity log to track agent's signing behavior
8. **Revoke** — Delete agent user to instantly revoke all signing authority

## Common gotchas

- **Forgetting to stamp requests** — All API calls must be signed with a valid credential (API key or passkey). Unsigned requests are rejected. Use a Stamper class or SDK to handle this automatically.
- **Mixing organization IDs** — Keep test and production organization IDs separate. Verify which org your code targets before deploying. A single typo sends requests to the wrong environment.
- **Policies are deny-by-default** — If no policy explicitly allows an action, it is rejected. Root users bypass policies, but non-root users need explicit ALLOW policies. Test policies with the intended user before going live.
- **Mnemonic length is immutable** — Once a wallet is created with a 12-word mnemonic, you cannot change it to 24 words. Choose the length upfront.
- **Exporting keys requires explicit export first** — Before deleting a wallet or private key, you must export it (or pass `deleteWithoutExport: true`). This prevents accidental loss of funds.
- **Sub-org parent has read-only access** — Parent orgs cannot modify sub-org resources. If you need to update a sub-org's policy, you must call the API as a user within that sub-org.
- **Rate limits are per-organization, not per-credential** — Distributing requests across multiple API keys does not increase your rate limit. All requests from a parent org and its sub-orgs share the same bucket.
- **Session tokens expire** — User sessions created via email/passkey have a TTL. Refresh sessions before they expire or re-authenticate the user.
- **Passkey RP ID must match your domain** — If you configure passkeys, the RP ID (relying party ID) must match your app's domain exactly. Mismatches cause passkey creation to fail.
- **Consensus expressions are evaluated at signing time** — A policy requiring `approvers.any(user, user.id == '<USER_ID>')` checks that the specified user is approving the activity. If that user is deleted before approval, the activity fails.

## Verification checklist

Before submitting work with Turnkey:

- [ ] API key and organization ID are correct and match the intended environment (test vs. production)
- [ ] All API requests are stamped with a valid credential (API key or passkey)
- [ ] Policies are tested with the intended user and produce expected allow/deny outcomes
- [ ] Wallets are created with the correct curve and address format for the target chain
- [ ] Transactions are signed with the correct wallet account address
- [ ] Rate limits are accounted for; retry logic uses exponential backoff with jitter
- [ ] Sub-organization isolation is verified (parent org cannot modify sub-org resources)
- [ ] User credentials are stored securely (API private keys, passkeys, session tokens)
- [ ] Activity IDs are logged for audit and debugging
- [ ] Backup and recovery flows are tested (export wallets, recover users via email)
- [ ] Production organization has an active subscription and sufficient signing quota
- [ ] Resource limits are not exceeded (max 100 users per org; use sub-orgs for more)

## Resources

**Comprehensive navigation:** https://docs.turnkey.com/llms.txt

**Critical documentation pages:**
1. [About Turnkey](https://docs.turnkey.com/get-started/about-turnkey) — Core concepts, architecture, and use cases
2. [API Reference](https://docs.turnkey.com/api-reference/overview/intro) — REST API endpoints, request/response formats, and error handling
3. [Policies Overview](https://docs.turnkey.com/features/policies/overview) — Policy engine, language, and examples for access control

---

> For additional documentation and navigation, see: https://docs.turnkey.com/llms.txt