Overview

Turnkey’s security and flexibility enables you to build cutting-edge user experiences, whether you’re using our bare-bones API or pre-built UI components. To make the most out of your implementation, we recommend reading through the following Concepts page for a better understanding of how our products work, and how to best utilize all of Turnkey’s features.

​

How Turnkey works

At the core of Turnkey is an important concept: instead of directly managing private keys, wallets are accessed through authenticators like passkeys, social logins, or API keys:

• Organizations (parent orgs) in Turnkey are top-level entities that contain users, wallets, and policies for a business, with the initial “parent organization” typically representing an entire Turnkey-powered application.
• Parent organizations can create sub-organizations (sub-orgs), which are fully segregated organizations nested under the parent organization. Parent orgs cannot modify the contents of a sub-org, and sub-orgs and typically represent an end user.
• Both parent organizations and sub-organizations contain a set of resources and authenticators that you can configure, including their own users, wallets, API keys, private keys, and policies.
• Activities (like signing transactions or creating users) are governed by policies created via Turnkey’s policy engine, though root users can bypass the policy engine when meeting root quorum requirements.
• Wallets in Turnkey are HD seed phrases that can generate multiple wallet accounts (addresses) for signing operations.

​

Managing Turnkey interactions and organizations

There are two primary ways for users to interact with Turnkey — via the Turnkey Dashboard, and by submitting activity requests via our public API.

The Turnkey Dashboard, which is where you’ll first create your Turnkey parent organization, is where root users of your parent organization will typically manage administrative activities. It supports passkey authentication only.

On the other hand, interactions with Turnkey at scale (primarily, interactions initiated by end users) can be done via programmatically calling the Turnkey public API and submitting activity requests, with a variety of authentication methods supported.

​

Concepts dictionary

For more details on individual concepts, feel free to explore our concept-specific documentation (also accessible through the left navbar).

​

Organizations

An organization is a logical grouping of resources like users, policies, and wallets. There are two types of organizations:

​

Users

Turnkey users are resources within organizations or sub-organizations that can submit activities to Turnkey via a valid credential (e.g., API key, passkey). These requests can be made either by making direct API calls or through the Turnkey Dashboard. Users must be set up to authenticate to Turnkey with credentials (API keys, passkeys), or via other authentication methods such as OAuth, or email auth, with upper limits on credentials defined here in our resource limits. Users can also have associated “tags” which are logical groupings that can be referenced in policies. Users can only submit activities within their given organization — they cannot take action across organizations.

There are two main types of users:

In parent organizations, a user often maps to an individual from your team with administrative privileges and responsibilities. In sub-organizations, which are often used to manage an end user’s resources, a user can represent an end user and their credentials. If there is only one user representing the end user with only end-user controlled credentials then this would be more akin to a standard non-custodial setup. However, this flexible primitive can often represent other aspects of your backend or application. For example, a Turnkey user might map to a:

• Backend service used to automate certain transactions
• Service with delegated access to take action on behalf of an end user
• Required co-signer for all end user transactions

For more information on Turnkey users look here.

​

Credentials

Interacting with the Turnkey API requires each API call to be authenticated by cryptographically stamping it with a credential. This process is abstracted away in our SDKs and ensures that the request cannot be tampered with as it travels to the secure enclave. Credentials include API keys and passkeys / Webauthn devices for all Users, while sub-organization users can also use email or OAuth to authenticate. Email and OAuth leverage API keys under the hood.

For more information on Turnkey user credentials look here.

​

Activities

Activities are specific actions taken by users, such as signing a transaction, adding a new user, or creating a sub-organization. Activity requests are always evaluated through our policy engine, and can evaluate to ALLOW, DENY, or REQUIRES_CONSENSUS (i.e., requires additional approvals before being allowed).

For more information on Turnkey activities look here.

​

Policies

Policies, enforced by Turnkey’s policy engine, grant users permissions to perform activities. These policies are a series of logical statements (e.g., User ID == 123 or ETH address == 0x543…9b34) that evaluate to either “ALLOW” or “DENY.” Through these policies you can set granular controls on which users can take which actions with which wallets. Policies can also require multi-party approval / consensus, meaning a threshold of certain users will be required to approve the activity. As mentioned above, the root quorum will bypass the policy engine.

For more information on Turnkey policies look here.

​

Wallets and Private Keys

Resources used to generate crypto addresses and sign transactions or messages. We currently support secp256k1 and ed25519 curves and have two main types:

Learn more about leveraging Wallets across different crypto ecosystems on our Ecosystem Support page.