Create and manage the root organization and isolated sub-organizations, each with their own root quorum, users, policies, and wallets. The primary multi-tenant primitive for embedding wallets per end user.
openapi: 3.0.1
info:
title: Turnkey API
description: >-
Turnkey is secure wallet infrastructure: an API-first key-management and
signing platform that generates private keys and signs payloads inside
verifiable secure enclaves (TEEs). The public API is an RPC-style REST API
under https://api.turnkey.com/public/v1 split into two families - read-only
`query` endpoints and state-changing `submit` activity endpoints. Every
request is an HTTP POST carrying an `X-Stamp` (or `X-Stamp-Webauthn`)
header containing a digital signature over the exact JSON POST body. The
stamp is verified by Turnkey's secure enclaves before the request is
processed and checked against the organization's policy engine.
termsOfService: https://www.turnkey.com/legal/terms
contact:
name: Turnkey Support
url: https://docs.turnkey.com
version: '1.0'
servers:
- url: https://api.turnkey.com
security:
- apiStamp: []
tags:
- name: Organizations
description: Root organization and sub-organization management.
- name: Wallets
description: HD wallets and wallet accounts.
- name: Private Keys
description: Standalone raw private keys.
- name: Signing
description: Transaction and raw payload signing activities.
- name: Users & Policies
description: Users, authenticators, API keys, and the policy engine.
paths:
/public/v1/submit/create_sub_organization:
post:
operationId: createSubOrganization
tags:
- Organizations
summary: Create a sub-organization
description: >-
Creates an isolated sub-organization with its own root users, root
quorum, and optionally an initial wallet. Submitted as an activity of
type ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSubOrganizationRequest'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/create_wallet:
post:
operationId: createWallet
tags:
- Wallets
summary: Create a wallet
description: >-
Creates an HD wallet and derives the requested wallet accounts.
Submitted as an activity of type ACTIVITY_TYPE_CREATE_WALLET.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWalletRequest'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/create_wallet_accounts:
post:
operationId: createWalletAccounts
tags:
- Wallets
summary: Create wallet accounts
description: >-
Derives additional wallet accounts from an existing wallet. Activity
type ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWalletAccountsRequest'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/create_private_keys:
post:
operationId: createPrivateKeys
tags:
- Private Keys
summary: Create private keys
description: >-
Generates one or more standalone raw private keys inside the enclave.
Activity type ACTIVITY_TYPE_CREATE_PRIVATE_KEYS_V2.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/sign_transaction:
post:
operationId: signTransaction
tags:
- Signing
summary: Sign a transaction
description: >-
Signs an unsigned transaction with the specified wallet account or
private key. Synchronous signing activity of type
ACTIVITY_TYPE_SIGN_TRANSACTION_V2, policy-checked before execution.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignTransactionRequest'
responses:
'200':
description: Signing activity completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/sign_raw_payload:
post:
operationId: signRawPayload
tags:
- Signing
summary: Sign a raw payload
description: >-
Signs an arbitrary payload with a wallet account address or private
key, with selectable encoding and hash function. Activity type
ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SignRawPayloadRequest'
responses:
'200':
description: Signing activity completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/sign_raw_payloads:
post:
operationId: signRawPayloads
tags:
- Signing
summary: Sign multiple raw payloads
description: >-
Signs a batch of raw payloads with a single key. Activity type
ACTIVITY_TYPE_SIGN_RAW_PAYLOADS_V2.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Signing activity completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/create_policies:
post:
operationId: createPolicies
tags:
- Users & Policies
summary: Create policies
description: >-
Adds one or more policies to the policy engine that authorizes
activities. Activity type ACTIVITY_TYPE_CREATE_POLICIES.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/create_users:
post:
operationId: createUsers
tags:
- Users & Policies
summary: Create users
description: >-
Adds users to an organization with associated API keys and
authenticators. Activity type ACTIVITY_TYPE_CREATE_USERS_V3.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/create_authenticators:
post:
operationId: createAuthenticators
tags:
- Users & Policies
summary: Create authenticators
description: >-
Registers WebAuthn/passkey authenticators for a user. Activity type
ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/export_wallet:
post:
operationId: exportWallet
tags:
- Wallets
summary: Export a wallet
description: >-
Exports a wallet's mnemonic encrypted to a caller-supplied target
public key. Activity type ACTIVITY_TYPE_EXPORT_WALLET.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/submit/import_wallet:
post:
operationId: importWallet
tags:
- Wallets
summary: Import a wallet
description: >-
Imports an externally generated mnemonic into a wallet. Activity type
ACTIVITY_TYPE_IMPORT_WALLET.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitActivityEnvelope'
responses:
'200':
description: Activity accepted/completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/query/get_activity:
post:
operationId: getActivity
tags:
- Signing
summary: Get an activity
description: Fetches a single activity and its result by id.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetActivityRequest'
responses:
'200':
description: Activity.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityResponse'
/public/v1/query/list_activities:
post:
operationId: listActivities
tags:
- Signing
summary: List activities
description: Lists activities for an organization with pagination and filters.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationScopedQuery'
responses:
'200':
description: List of activities.
content:
application/json:
schema:
type: object
/public/v1/query/list_wallets:
post:
operationId: listWallets
tags:
- Wallets
summary: List wallets
description: Lists the wallets in an organization.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationScopedQuery'
responses:
'200':
description: List of wallets.
content:
application/json:
schema:
$ref: '#/components/schemas/ListWalletsResponse'
/public/v1/query/get_wallet:
post:
operationId: getWallet
tags:
- Wallets
summary: Get a wallet
description: Fetches a single wallet by id.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetWalletRequest'
responses:
'200':
description: Wallet.
content:
application/json:
schema:
type: object
/public/v1/query/list_wallet_accounts:
post:
operationId: listWalletAccounts
tags:
- Wallets
summary: List wallet accounts
description: Lists the derived accounts of a wallet.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListWalletAccountsRequest'
responses:
'200':
description: List of wallet accounts.
content:
application/json:
schema:
type: object
/public/v1/query/list_private_keys:
post:
operationId: listPrivateKeys
tags:
- Private Keys
summary: List private keys
description: Lists standalone private keys in an organization.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationScopedQuery'
responses:
'200':
description: List of private keys.
content:
application/json:
schema:
type: object
/public/v1/query/list_users:
post:
operationId: listUsers
tags:
- Users & Policies
summary: List users
description: Lists users in an organization.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationScopedQuery'
responses:
'200':
description: List of users.
content:
application/json:
schema:
type: object
/public/v1/query/list_policies:
post:
operationId: listPolicies
tags:
- Users & Policies
summary: List policies
description: Lists policies in an organization.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationScopedQuery'
responses:
'200':
description: List of policies.
content:
application/json:
schema:
type: object
/public/v1/query/whoami:
post:
operationId: whoami
tags:
- Users & Policies
summary: Who am I
description: >-
Returns the organization and user associated with the stamping
credential of the request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WhoamiRequest'
responses:
'200':
description: Caller identity.
content:
application/json:
schema:
$ref: '#/components/schemas/WhoamiResponse'
components:
securitySchemes:
apiStamp:
type: apiKey
in: header
name: X-Stamp
description: >-
Base64URL-encoded JSON stamp `{publicKey, signature, scheme}` where
`signature` is a DER-encoded, hex-encoded signature over the exact JSON
POST body produced by the registered API key. `scheme` is one of
SIGNATURE_SCHEME_TK_API_P256, SIGNATURE_SCHEME_TK_API_SECP256K1,
SIGNATURE_SCHEME_TK_API_ED25519, or
SIGNATURE_SCHEME_TK_API_SECP256K1_EIP191. Passkey-stamped requests use
the alternate `X-Stamp-Webauthn` header carrying a WebAuthn assertion
`{credentialId, authenticatorData, clientDataJson, signature}` (plain
JSON, not base64URL-encoded) over a SHA256 hash of the POST body.
webauthnStamp:
type: apiKey
in: header
name: X-Stamp-Webauthn
description: >-
Plain-JSON WebAuthn assertion stamp for passkey-authenticated requests.
schemas:
SubmitActivityEnvelope:
type: object
description: >-
Common envelope for all submit (mutation) activities. The `type`
selects the activity and `parameters` carries the activity-specific
body.
required:
- type
- timestampMs
- organizationId
- parameters
properties:
type:
type: string
description: The ACTIVITY_TYPE_* discriminator for this activity.
example: ACTIVITY_TYPE_CREATE_WALLET
timestampMs:
type: string
description: Client timestamp in milliseconds, replay-protected.
example: '1746736509954'
organizationId:
type: string
description: The organization or sub-organization id the activity targets.
parameters:
type: object
description: Activity-specific parameters.
OrganizationScopedQuery:
type: object
required:
- organizationId
properties:
organizationId:
type: string
CreateSubOrganizationRequest:
allOf:
- $ref: '#/components/schemas/SubmitActivityEnvelope'
- type: object
properties:
parameters:
$ref: '#/components/schemas/CreateSubOrganizationParams'
CreateSubOrganizationParams:
type: object
required:
- subOrganizationName
- rootUsers
- rootQuorumThreshold
properties:
subOrganizationName:
type: string
rootUsers:
type: array
items:
type: object
rootQuorumThreshold:
type: integer
wallet:
type: object
description: Optional initial wallet to create with the sub-organization.
CreateWalletRequest:
allOf:
- $ref: '#/components/schemas/SubmitActivityEnvelope'
- type: object
properties:
type:
type: string
enum:
- ACTIVITY_TYPE_CREATE_WALLET
parameters:
$ref: '#/components/schemas/CreateWalletParams'
CreateWalletParams:
type: object
required:
- walletName
- accounts
properties:
walletName:
type: string
accounts:
type: array
items:
$ref: '#/components/schemas/WalletAccountParams'
mnemonicLength:
type: integer
enum: [12, 15, 18, 21, 24]
default: 12
CreateWalletAccountsRequest:
allOf:
- $ref: '#/components/schemas/SubmitActivityEnvelope'
- type: object
properties:
parameters:
type: object
required:
- walletId
- accounts
properties:
walletId:
type: string
accounts:
type: array
items:
$ref: '#/components/schemas/WalletAccountParams'
WalletAccountParams:
type: object
required:
- curve
- pathFormat
- path
- addressFormat
properties:
curve:
type: string
enum:
- CURVE_SECP256K1
- CURVE_ED25519
- CURVE_P256
pathFormat:
type: string
enum:
- PATH_FORMAT_BIP32
path:
type: string
example: m/44'/60'/0'/0/0
addressFormat:
type: string
example: ADDRESS_FORMAT_ETHEREUM
SignTransactionRequest:
allOf:
- $ref: '#/components/schemas/SubmitActivityEnvelope'
- type: object
properties:
parameters:
type: object
required:
- signWith
- unsignedTransaction
- type
properties:
signWith:
type: string
description: Wallet account address or private key id to sign with.
unsignedTransaction:
type: string
description: Hex-encoded unsigned transaction.
type:
type: string
enum:
- TRANSACTION_TYPE_ETHEREUM
- TRANSACTION_TYPE_SOLANA
- TRANSACTION_TYPE_TRON
SignRawPayloadRequest:
allOf:
- $ref: '#/components/schemas/SubmitActivityEnvelope'
- type: object
properties:
parameters:
type: object
required:
- signWith
- payload
- encoding
- hashFunction
properties:
signWith:
type: string
payload:
type: string
encoding:
type: string
enum:
- PAYLOAD_ENCODING_HEXADECIMAL
- PAYLOAD_ENCODING_TEXT_UTF8
hashFunction:
type: string
enum:
- HASH_FUNCTION_NO_OP
- HASH_FUNCTION_SHA256
- HASH_FUNCTION_KECCAK256
- HASH_FUNCTION_NOT_APPLICABLE
GetActivityRequest:
type: object
required:
- organizationId
- activityId
properties:
organizationId:
type: string
activityId:
type: string
GetWalletRequest:
type: object
required:
- organizationId
- walletId
properties:
organizationId:
type: string
walletId:
type: string
ListWalletAccountsRequest:
type: object
required:
- organizationId
- walletId
properties:
organizationId:
type: string
walletId:
type: string
paginationOptions:
type: object
WhoamiRequest:
type: object
required:
- organizationId
properties:
organizationId:
type: string
WhoamiResponse:
type: object
properties:
organizationId:
type: string
organizationName:
type: string
userId:
type: string
username:
type: string
ListWalletsResponse:
type: object
properties:
wallets:
type: array
items:
type: object
properties:
walletId:
type: string
walletName:
type: string
createdAt:
type: object
updatedAt:
type: object
ActivityResponse:
type: object
description: Standard activity envelope returned by submit and query endpoints.
properties:
activity:
type: object
properties:
id:
type: string
organizationId:
type: string
status:
type: string
enum:
- ACTIVITY_STATUS_CREATED
- ACTIVITY_STATUS_PENDING
- ACTIVITY_STATUS_COMPLETED
- ACTIVITY_STATUS_FAILED
- ACTIVITY_STATUS_CONSENSUS_NEEDED
- ACTIVITY_STATUS_REJECTED
type:
type: string
result:
type: object
description: >-
Activity-specific result, e.g. createWalletResult
{walletId, addresses[]} or signTransactionResult
{signedTransaction} or signRawPayloadResult {r, s, v}.