FAQ
Authentication and credentials
When you authenticate to the Turnkey dashboard, your email is used to lookup your organization and associated credentials. Currently we do not allow multiple users to be associated with the same email address.
Asymmetric cryptography offers various security benefits to you:
- Turnkey cannot leak your API private keys, even if compromised, because Turnkey only knows your API public keys.
- Your API private key stays on the server you generated it for. This means there’s a lower risk of key exfiltration compared to other methods where an API key, or API credentials in general, are generated in one place (web browser, company server), transported via a second (copy/paste, email, PDF document) and used in a third place (your server).
Signing the whole payload is a way for Turnkey to know:
- That you are in possession of your API key (because we can verify the signature you attach to requests).
- That the person or program signing is approving the current request (not just any request).
Concretely, Turnkey needs the following:
- The original request you sent: this is achieved by simply receiving the HTTP request and its body
- That your API key was used to approve the request: this is achieved by checking the signature contained in the
X-Stampheader. For this verification we need the serialized POST body, your API public key, and the signature. This is all contained in the header value. - That the request is legitimate: this is achieved by parsing the serialized request to make sure the intent is correct. This happens all the way down in our Secure Enclaves. For example, when you send a request to create a new Private Key, our policy engine parses your original request to independently derive the type of request, the payload to sign, etc. This guards against man-in-the-middle attacks.
Turnkey would not be able to have its enclaves verify signatures and check the request intent if we didn’t have your signature on the whole payload.
A Turnkey API key is simply a way to authenticate requests to Turnkey. Crypto assets are not tied to it in any way.
Think about Turnkey API keys as an access-gating mechanism to Turnkey functionality. They’re flexible in what they can do (you get to decide this with Policies!), and revocable if they are lost or compromised.
Losing your Turnkey API key doesn’t mean you’ll lose your crypto:
- By default, your API key is not able to move funds
- If you’ve changed policies so that your API key is allowed to unilaterally move funds, you may be at risk. Leverage the Turnkey UI to revoke your API key as soon as possible.
Talk to our team (hello@turnkey.com) if you want to get in touch and talk more in-depth.
We require a recent timestamp in the timestampMs field for each new activity submission.
Our secure enclaves have their own, independent, secure source of time. We currently require request timestamps to be less than an hour old, and up to 5 minutes in the future.
You can, but it doesn’t mean you should. If you use your existing crypto private key as a turnkey API key, you are coupling Turnkey access with your crypto wallet. In essence, the risk profile of this key goes up. It’s a bit like re-using passwords across many sites. Turnkey highly recommends creating a fresh public/private key pair if you need programmatic Turnkey access.
While we don’t have an off the shelf recipe, one potential approach is:
- At sub-org creation, create your root user with 2+ API keys. One for day-to-day signing, and the other(s) securely stored.
- If the day-to-day key is leaked, then you can use one of the secure, additional keys to remove it from all impacted sub-orgs via
ACTIVITY_TYPE_DELETE_API_KEYS.
Reach out to our team (hello@turnkey.com) for additional guidance.
Limits
See resource limits.
Our public API currently limits users to a maximum of 60 RPS (Requests Per Second). Specific headers are returned to indicate current quota:
ratelimit-limit: indicates the total quota (60)ratelimit-remaining: indicates the current quotax-rate-limit-request-forwarded-forandx-rate-limit-request-remote-addr: echo back your remote IP and forwarded-for IP for debugging purposes
When rate limits are exceeded, an error with HTTP 429 is returned with the following message: Too many requests. Please wait and try again in a few seconds.
This limit is on a per IP address basis: if you have multiple servers making requests to the turnkey API under a different IP address, each server is subject to the 60 RPS limit individually.
Please get in touch with us (help@turnkey.com) if you need this limit adjusted for your use-case.
Supported functionality
Yes! See Ethereum (EVM) support on Turnkey for more information and concrete examples.
Yes! See Solana (SVM) support on Turnkey for more information and concrete examples.
Yes! See Bitcoin support on Turnkey for more information and concrete examples.
Turnkey currently supports SECP256k1 and Ed25519.
Turnkey’s primitive for private keys and wallet is the cryptographic curve rather than specific cryptocurrencies. Our approach to supporting assets is tiered, see this page for more information.
We have deeper support for Ethereum, Solana, and Bitcoin.
If there are specific ecosystems or chains you’d like to see us offer deeper support for, please let us know by contacting us at hello@turnkey.com, on X, or on Slack.
Turnkey does not offer native support for transaction construction and broadcast, instead we focus on transaction signing.
We suggest you use blockchain-specific libraries, like Ethers.js for Ethereum, to construct transactions. We offer simple scripts leveraging ethers.js to help you with basic transaction construction.
You can use any blockchain node provider, like Infura or Alchemy, to broadcast your transactions.
In the ECDSA context, messages are hashed before signing. Turnkey can perform this hashing for you, as we support two hash functions: HASH_FUNCTION_KECCAK256 and HASH_FUNCTION_SHA256 (for Ethereum and Bitcoin ecosystems respectively). If your message had already been hashed, you should use the HASH_FUNCTION_NO_OP option to sign the raw hash, in which case Turnkey will sign the payload as is. HASH_FUNCTION_NO_OP also has privacy implications: if a raw hashed message is passed in, Turnkey has no knowledge of the underlying pre-image.
As an example, in our Viem package, the message is hashed before signing.
Unlike ECDSA, in which a message is hashed as a separate step before signing, when using Ed25519, hashing is performed during signature computation, and thus cannot be skipped (for more details on the standard, see RFC 8032: “Ed25519 is EdDSA instantiated with: …H(x) = SHA-512"). As a result, we have a special HASH_FUNCTION_NOT_APPLICABLE option for when you use ed25519/EdDSA.
An example for this case can be found in our Solana signer.
Guidance
Yes, we report critical incidents at turnkey-status.com.
Typically we recommend that you create “test” organizations to test the API and functionality freely. When you are ready to go to production, use a “main” organization used for production only.
To do this you can use email aliases: if firstname@domain.com is your email, you can sign up for a new Turnkey organization with firstname+test@domain.com to have a test playground.
If you need many test organizations or if you have specific questions, our team is happy to help you get set up.
Turnkey is priced per signature, i.e. any transaction or raw payload successfully signed by a private key created on Turnkey. Turnkey offers 25 free signatures each month. To execute more than 25 transactions in a given month, you are required to have a credit card on file or active enterprise plan on your account. To upgrade your plan, navigate to Account Settings from the menu in the top right-hand corner in the Turnkey dashboard and follow the instructions.
For more information about pricing and billing, check out the pricing page.
Join our slack community here to get support with your integration, share product feedback, and connect with other crypto builders. Or, reach out directly to help@turnkey.com. Teams that are looking for more in-depth integration support can upgrade to an Enterprise plan via hello@turnkey.com.
To request the deletion of your parent organization from our records, please email us at privacy@turnkey.com.
Turnkey is not currently available to users in any countries currently subject to US OFAC sanctions.
Check out our whitepaper, available at whitepaper.turnkey.com! It covers our foundations and architecture in great detail.