-
+
-
- 
-
+
### Recovery Flow
@@ -96,9 +103,9 @@ The recovery process consists of two phases:
1. **Initiation**: Generates a temporary recovery credential and sends it via email
2. **Finalization**: User decrypts the recovery credential and uses it to sign an `ACTIVITY_TYPE_RECOVER_USER` activity, which can add new authenticators to regain account access
-
-
-
+
## Authorization
@@ -120,23 +127,25 @@ Specifically:
### Recovery
- `ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY`:
+
- Initiates the recovery process
- Requires proper authorization via policies
- Can target any user in the organization or sub-organizations
+
- `ACTIVITY_TYPE_RECOVER_USER`:
+
- Must be signed by the recovery credential received via email
- Users can add credentials to their own user when authenticated
- Recovery credentials expire after 15 minutes
- Only the most recent recovery credential remains valid
- Users can add new authenticators to regain account access when authenticated with a recovery credential
-
+
-
- 
- 
-
+
+
+ 
+
+
- 
-
+
1. Your app frontend triggers a passkey prompt.
2. Your end-user uses their device to produce a signature with their passkey, and a signed request is produced.
@@ -25,57 +18,58 @@ A typical passkey flow is composed of 4 main steps, depicted below:
This flow happens once for **registration** and for each subsequent **authentication** or signature request. The main difference is the browser APIs used to trigger the passkey prompt in step (1):
-- **Passkey registration** uses `navigator.credentials.create`(as described in [this guide](https://web.dev/passkey-registration/)). `navigator.credentials.create` triggers the creation of a **new** passkey.
-- **Passkey authentication** uses `navigator.credentials.get`. See [this guide](https://web.dev/passkey-form-autofill/) for more information. `navigator.credentials.get` triggers a signature prompt for an **existing** passkey.
+* **Passkey registration** uses `navigator.credentials.create`(as described in [this guide](https://web.dev/passkey-registration/)). `navigator.credentials.create` triggers the creation of a **new** passkey.
+* **Passkey authentication** uses `navigator.credentials.get`. See [this guide](https://web.dev/passkey-form-autofill/) for more information. `navigator.credentials.get` triggers a signature prompt for an **existing** passkey.
## Our SDK can help
Our SDK has integrated passkey functionality, and we've built examples to help you get started.
-- [`@turnkey/http`](https://www.npmjs.com/package/@turnkey/http) has a helper to trigger passkey registration (`getWebAuthnAttestation`). You can see it in action in our [`with-federated-passkeys`](https://github.com/tkhq/sdk/tree/main/examples/with-federated-passkeys) example: [direct code link](https://github.com/tkhq/sdk/blob/a2bfbf3cbd6040902bbe4c247900ac560be42925/examples/with-federated-passkeys/src/pages/index.tsx#L88)
-- [`@turnkey/webauthn-stamper`](https://www.npmjs.com/package/@turnkey/webauthn-stamper) is a passkey-compatible stamper which integrates seamlessly with `TurnkeyClient`:
+* [`@turnkey/http`](https://www.npmjs.com/package/@turnkey/http) has a helper to trigger passkey registration (`getWebAuthnAttestation`). You can see it in action in our [`with-federated-passkeys`](https://github.com/tkhq/sdk/tree/main/examples/with-federated-passkeys) example: [direct code link](https://github.com/tkhq/sdk/blob/a2bfbf3cbd6040902bbe4c247900ac560be42925/examples/with-federated-passkeys/src/pages/index.tsx#L88)
+
+* [`@turnkey/webauthn-stamper`](https://www.npmjs.com/package/@turnkey/webauthn-stamper) is a passkey-compatible stamper which integrates seamlessly with `TurnkeyClient`:
- ```js
- import { WebauthnStamper } from "@turnkey/webauthn-stamper";
- import { TurnkeyClient, createActivityPoller } from "@turnkey/http";
+```ts
+import { WebauthnStamper } from "@turnkey/webauthn-stamper";
+import { TurnkeyClient, createActivityPoller } from "@turnkey/http";
- const stamper = new WebAuthnStamper({
- rpId: "your.app.xyz",
- });
+const stamper = new WebAuthnStamper({
+ rpId: "your.app.xyz",
+});
- // New HTTP client able to sign with passkeys
- const httpClient = new TurnkeyClient(
- { baseUrl: "https://api.turnkey.com" },
- stamper
- );
+// New HTTP client able to sign with passkeys
+const httpClient = new TurnkeyClient(
+ { baseUrl: "https://api.turnkey.com" },
+ stamper
+);
- // This will produce a signed request that can be POSTed from anywhere.
- // The `signedRequest` has a URL, a POST body, and a "stamp" (HTTP header name and value)
- const signedRequest = await httpClient.stampCreatePrivateKeys(...)
+// This will produce a signed request that can be POSTed from anywhere.
+// The `signedRequest` has a URL, a POST body, and a "stamp" (HTTP header name and value)
+const signedRequest = await httpClient.stampCreatePrivateKeys(...)
- // Alternatively, you can POST directly from your frontend.
- // Our HTTP client will use the webauthn stamper and the configured baseUrl automatically!
- const activityPoller = createActivityPoller({
- client: client,
- requestFn: client.createPrivateKeys,
- });
+// Alternatively, you can POST directly from your frontend.
+// Our HTTP client will use the webauthn stamper and the configured baseUrl automatically!
+const activityPoller = createActivityPoller({
+ client: client,
+ requestFn: client.createPrivateKeys,
+});
- // Contains the activity result; no backend proxy needed!
- const completedActivity = await activityPoller({
- type: "ACTIVITY_TYPE_CREATE_PRIVATE_KEYS_V2",
- // (omitting the rest of this for brevity)
- })
- ```
+// Contains the activity result; no backend proxy needed!
+const completedActivity = await activityPoller({
+ type: "ACTIVITY_TYPE_CREATE_PRIVATE_KEYS_V2",
+ // (omitting the rest of this for brevity)
+})
+```
-- [`@turnkey/viem`](https://www.npmjs.com/package/@turnkey/viem) is a package wrapping all of the above so that you work directly with Viem without worrying about passkeys. See [this demo](https://github.com/tkhq/sdk/tree/main/examples/with-viem-and-passkeys).
+* [`@turnkey/viem`](https://www.npmjs.com/package/@turnkey/viem) is a package wrapping all of the above so that you work directly with Viem without worrying about passkeys. See [this demo](https://github.com/tkhq/sdk/tree/main/examples/with-viem-and-passkeys).
Regardless of whether you use our helpers and abstractions, take a look at [our registration and authentication options guide](/authentication/passkeys/options). This will help you choose the right options for your passkey flow.
If you have questions, feedback, or find yourself in need of an abstraction or integration that doesn't exist yet, please get in touch with us! You can
-- Create an [issue on our SDK repo](https://github.com/tkhq/sdk/issues)
-- Join our slack community [here](https://join.slack.com/t/clubturnkey/shared_invite/zt-2837d2isy-gbH60kJ~XnXSSFHiqVOrqw)
-- Contact us at
- 
- 
-
+
+
+
+ 
+
+
- 
-
+
This UI isn't very helpful, so we recommend making the timeout long (5 minutes). The less your users see this, the better.
@@ -35,28 +27,21 @@ The `rp` options is an object with 2 fields: `id` and `name`.
`rp.id` (aka RPID) should be your app top-level domain. For example, if your app is hosted on `https://your.app.xyz` the RPID should be `app.xyz` unless you have good reasons to do otherwise (see below).
-
- 
-
+
`rp.name` doesn't show up in the popup so can be set to anything. We recommend setting it to the correctly capitalized name of your app, in case browsers start showing it in their native UIs in the future.
@@ -74,12 +59,15 @@ The integers `-7` and `-257` are algorithm identifiers for ES256 (aka P256) and
The `user` field has three sub-fields:
-- `id`: also known as "user handle", isn't visible to the end-user. We **strongly recommend setting this to a random value** (e.g. `const id = new Uint8Array(32); crypto.getRandomValues(id)`) to make sure a new passkey is created. Be aware: **if you accidentally set this value to an existing user handle, the corresponding passkey will be overridden!** [This section of spec](https://www.w3.org/TR/webauthn-2/#dictionary-user-credential-params) is clear on the matter: "the user handle ought not be a constant value across different accounts, even for non-discoverable credentials".
-- `name`: this will show up in the passkey list modal (see screenshot below). We recommend setting this to something the user will recognize: their email, the name of your app, or potentially leave this up to the user:
-
- 
-
+
+
+* `displayName`: as far as we can tell this doesn't show up in current browser UIs. It might show up in future iterations so it's best to populate this with the same value as `name`.
### `authenticatorSelection`
@@ -89,10 +77,10 @@ This option has lots of consequences for UX, and it has many sub-options, outlin
This option, if set, restricts the type of authenticators that can be registered. See the table below for the values this option can take and their effect on registration prompts (captured via Chrome on a MacBook Pro).
-| Empty (default) | `platform` | `cross-platform` |
-| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| If you want broad compatibility, leave this option empty, and the browser UI will allow for both internal and external passkeys. | If set to `platform`, only internal authenticators (face ID, touch ID, and so on) can be registered. | If set to `cross-platform`, only passkeys from other devices or attached via USB are allowed. |
-| 
| 
| 
|
+| Empty (default) | `platform` | `cross-platform` |
+| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| If you want broad compatibility, leave this option empty, and the browser UI will allow for both internal and external passkeys. | If set to `platform`, only internal authenticators (face ID, touch ID, and so on) can be registered. | If set to `cross-platform`, only passkeys from other devices or attached via USB are allowed. |
+| 
| 
| 
|
#### `requireResidentKey` and `residentKey`
@@ -104,9 +92,9 @@ Important note: the default for `requireResidentKey` (`discouraged`) results in
"User verification" refers to mechanisms on the authenticators themselves such as PIN codes or biometric/fingerprint readers. This flag can be set to:
-- `discouraged`: yubikey PINs won't be required even if the device technically supports it. We've found that for TouchID/FaceID, authentication will still be required however.
-- `preferred`: yubikey PINs and other authentication mechanisms will be required if supported, but devices without them will be accepted.
-- `required`: authenticators without user verification support won't be accepted.
+* `discouraged`: yubikey PINs won't be required even if the device technically supports it. We've found that for TouchID/FaceID, authentication will still be required however.
+* `preferred`: yubikey PINs and other authentication mechanisms will be required if supported, but devices without them will be accepted.
+* `required`: authenticators without user verification support won't be accepted.
To maximize compatibility we recommend setting `userVerification` to "discouraged" or "preferred" because some authenticators do not support user verification.
@@ -132,30 +120,23 @@ List of objects restricting which credentials can be used during authentication.
Each object in this list has an ID (the credential ID) and a list of transports (e.g. "hybrid", "internal", "usb", etc). The `transports` list is **optional** but results in better, more targeted prompts. For example, here are screenshot of targeted prompts captured on Chrome, on a MacBook laptop:
-| `transports: ["internal"]` | `transports: ["usb"]` | `transports: ["hybrid"]` |
-| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| 
| 
| 
|
+| `transports: ["internal"]` | `transports: ["usb"]` | `transports: ["hybrid"]` |
+| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| 
| 
| 
|
The credential ID needs to be passed as a buffer but is returned from registration as a base64-encoded value: make sure to decode it (in JavaScript: `Buffer.from(storedCredentialId, "base64")`) to avoid issues.
If the wrong credential ID is specified, `transports: ["internal"]` is set, browsers error right away because they can enumerate internal credentials. Chrome, for example, displays the following error:
-
- 
-
+
However, if the wrong credential ID is specified without `transports` set (or with other-than-internal `transports` set), browsers won't error right away because they can't enumerate external credentials. They will display an error once the user has pressed their security key or gone through the cross-device passkey flow:
-
- 
-
+
### `attestation`
diff --git a/docs/documentation/authentication/sessions.md b/authentication/sessions.mdx
similarity index 53%
rename from docs/documentation/authentication/sessions.md
rename to authentication/sessions.mdx
index 45df9b38..caf81a8e 100644
--- a/docs/documentation/authentication/sessions.md
+++ b/authentication/sessions.mdx
@@ -1,17 +1,14 @@
---
-sidebar_position: 5
-description: Learn about user sessions on Turnkey
-slug: /authentication/sessions
+title: "Sessions"
+description: "Turnkey sessions allow a user to take multiple, contiguous actions in a defined period of time."
---
-# Sessions
-
## What is a session?
-Turnkey sessions allow a user to take multiple, contiguous actions in a defined period of time. Such actions can be divided into two buckets:
+Such actions can be divided into two buckets:
-- Read operations: Retrieving data (e.g., viewing wallet balances)
-- Write operations: Modifying data or performing sensitive actions (e.g., signing transactions)
+* Read operations: Retrieving data (e.g., viewing wallet balances)
+* Write operations: Modifying data or performing sensitive actions (e.g., signing transactions)
## How can I create a session?
@@ -25,9 +22,9 @@ By default, a parent organization has read access to all of its sub-organization
#### Client side access
-Separately, if you would like the client to have all read requests encapsulated (instead of reading data via a proxy like in the previous approach), the client can initiate a read-only session via a [CreateReadOnlySession activity](https://docs.turnkey.com/api#tag/Sessions/operation/CreateReadOnlySession). This activity returns a session string that, if passed into an HTTP request via `X-Session` header, gives permission to perform reads. Note that because this is an activity performed by an end-user, it requires authentication (e.g. via passkey).
+Separately, if you would like the client to have all read requests encapsulated (instead of reading data via a proxy like in the previous approach), the client can initiate a read-only session via a [CreateReadOnlySession activity](/api-reference/sessions/create-read-only-session). This activity returns a session string that, if passed into an HTTP request via `X-Session` header, gives permission to perform reads. Note that because this is an activity performed by an end-user, it requires authentication (e.g. via passkey).
-If you’d like to do this via our SDK abstractions, you can leverage the [login](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/sdk-browser/src/sdk-client.ts#L231-L255)1 method, which creates a `CreateReadOnlySession` activity under the hood. It stores the resulting session string in [Local Storage](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/sdk-browser/src/sdk-client.ts#L242-L252)2, and subsequent requests to fetch data from Turnkey injects the session stored here at [call time](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/sdk-browser/src/__generated__/sdk-client-base.ts#L45-L47)3 within `@turnkey/sdk-browser`.
+If you’d like to do this via our SDK abstractions, you can leverage the [login](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/sdk-browser/src/sdk-client.ts#L231-L255)1 method, which creates a `CreateReadOnlySession` activity under the hood. It stores the resulting session string in [Local Storage](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/sdk-browser/src/sdk-client.ts#L242-L252)2, and subsequent requests to fetch data from Turnkey injects the session stored here at [call time](https://github.com/tkhq/sdk/blob/6b3ea14d1184c5394449ecaad2b0f445e373823f/packages/sdk-browser/src/__generated__/sdk-client-base.ts#L45-L47)3 within `@turnkey/sdk-browser`.
### Read-write sessions
@@ -35,11 +32,11 @@ In contrast to read-only sessions, a read-write session makes sense when a user
#### Creating a read-write session
-Developers can leverage the [CreateReadWriteSession](https://docs.turnkey.com/api#tag/Sessions/operation/CreateReadWriteSession) activity, which requires a target embedded key and returns a credential bundle. This is a pattern that many core, secure flows follow, including Email Auth, and OTP Auth. See [documentation](/authentication/email) for more details.
+Developers can leverage the [CreateReadWriteSession](/api-reference/sessions/create-read-write-session) activity, which requires a target embedded key and returns a credential bundle. This is a pattern that many core, secure flows follow, including Email Auth, and OTP Auth. See [documentation](/authentication/email#mechanism-and-cryptographic-details) for more details.
-
- 
-
+
As illustrated above, once you have a target embedded key in place on the client side, you can call `CreateReadWriteSession`, get the resulting credential bundle, and decrypt it on the client side using the “TEK”. Upon decryption, the result is a usable Turnkey API key that can be used to make both read and write requests.
@@ -53,17 +50,17 @@ Your next question might be: where can I get the target embedded key? There are
#### iframes:
-Turnkey hosts an iframe for use cases such as this one at https://auth.turnkey.com (see [here](https://github.com/tkhq/frames/tree/main/auth) for code implementation). It’s to be used in conjunction with our [@turnkey/iframe-stamper](https://docs.turnkey.com/sdks/advanced/iframe-stamper), but note that some complexity can be abstracted away if using @turnkey/sdk-react. See this [code example](https://docs.turnkey.com/embedded-wallets/code-examples/create-passkey-session) for more.
+Turnkey hosts an iframe for use cases such as this one at [https://auth.turnkey.com](https://auth.turnkey.com) (see [here](https://github.com/tkhq/frames/tree/main/auth) for code implementation). It’s to be used in conjunction with our [@turnkey/iframe-stamper](/sdks/advanced/iframe-stamper), but note that some complexity can be abstracted away if using @turnkey/sdk-react. See this [code example](/embedded-wallets/code-examples/create-passkey-session) for more.
The iframe is responsible for holding the “TEK” mentioned in the previous diagram. In addition to housing the TEK, it exposes some methods to be able to interact with (but not extract!) the TEK. The end result is that the iframe can safely and securely sign requests to Turnkey. If you would like to take a look at lower level implementation details, see [here](https://github.com/tkhq/sdk/blob/main/packages/iframe-stamper/src/index.ts).
There are a few considerations to note when using sessions with iframes:
-- Sessions only last as long as the iframe is maintained on the browser
-- On desktop, this generally is as long as the user doesn’t completely quit the browser
-- On mobile, specifically iOS devices, this behavior is much more finicky as iOS is aggressive in clearing out data contained within iframes
-- In either case, sessions are indeed shared across different browser tabs and windows
-- May be more difficult to set up to use in conjunction with React Native or other frameworks
+* Sessions only last as long as the iframe is maintained on the browser
+* On desktop, this generally is as long as the user doesn’t completely quit the browser
+* On mobile, specifically iOS devices, this behavior is much more finicky as iOS is aggressive in clearing out data contained within iframes
+* In either case, sessions are indeed shared across different browser tabs and windows
+* May be more difficult to set up to use in conjunction with React Native or other frameworks
#### Local Storage:
@@ -71,9 +68,9 @@ Another potential host for a TEK is directly in Local Storage. We’ve created l
Here are some considerations for using Local Storage:
-- Generally more durable than using iframes in various contexts (i.e. web on both desktop and mobile)
-- Can be used in other settings such as React Native, Flutter, etc.
-- As mentioned, the developer has complete control over the target embedded key. As a result, it’s important to manage this credential with caution.
+* Generally more durable than using iframes in various contexts (i.e. web on both desktop and mobile)
+* Can be used in other settings such as React Native, Flutter, etc.
+* As mentioned, the developer has complete control over the target embedded key. As a result, it’s important to manage this credential with caution.
For an example that leverages Local Storage with Email Auth, see [here](https://github.com/tkhq/sdk/tree/main/examples/email-auth-local-storage).
@@ -81,53 +78,48 @@ For an example that leverages Local Storage with Email Auth, see [here](https://
Another option is to create an API key and store it directly within Local Storage. However, this is a riskier setup than via TEK (as mentioned in the above Local Storage section), as anyone who is able to access this client-side API key has full access to a User.
-
-
### Sessions FAQ
-
-#### How can I refresh a session?
-
-Once a user has a valid session, it is trivial to use that session to create a new session. It is possible to reuse the same loginWithReadWriteSession abstraction, as this will create a brand new session and automatically store the resulting credential bundle in local storage.
-
-#### How can I delete a session?
-
-In order to delete a session, simply remove all user-related artifacts from Local Storage. See implementation in context [here](https://github.com/tkhq/sdk/blob/9e9943387123d077fa3b7f38ef3be007291a2c8a/packages/sdk-browser/src/sdk-client.ts#L242-L255).
-
-```javascript
-/**
- * Clears out all data pertaining to a user session.
- *
- * @returns {Promise
- 
-
+
1. **End-User** enters the signup flow on the app, gets redirected to Google for authentication.
-1. Upon completion, the **Parent**'s backend receives the OIDC token authenticating **End-User**.
-1. This token is used inside of a `CREATE_SUB_ORGANIZATION` activity to register Google as the Oauth provider under the root user.
-1. **Turnkey** verifies the OIDC token and creates a new sub-organization.
+2. Upon completion, the **Parent**'s backend receives the OIDC token authenticating **End-User**.
+3. This token is used inside of a `CREATE_SUB_ORGANIZATION` activity to register Google as the Oauth provider under the root user.
+4. **Turnkey** verifies the OIDC token and creates a new sub-organization.
The user is now registered: a sub-organization under the parent organization has been created with a a root user, authenticated via an OAuth Provider. Concretely:
-- `issuer` is set to `https://accounts.google.com`
-- `audience` is set to `
- 
-
+
1. **End-User** enters the login flow on the app, gets redirected to Google for authentication.
-1. Upon completion, `Parent backend` receives the OIDC token authenticating **End-User**.
-1. This token is used inside of an `OAUTH` activity, signed by the **Parent**'s backend.
-1. **Turnkey** verifies the OIDC token and encrypts an expiring API key credential to **End-User**.
-1. **End-User** decrypts the credential.
+2. Upon completion, `Parent backend` receives the OIDC token authenticating **End-User**.
+3. This token is used inside of an `OAUTH` activity, signed by the **Parent**'s backend.
+4. **Turnkey** verifies the OIDC token and encrypts an expiring API key credential to **End-User**.
+5. **End-User** decrypts the credential.
The user is now authenticated and able to perform Turnkey activities.
@@ -68,17 +60,17 @@ We've designed a new secure enclave to fetch TLS content securely and bring [non
To verify an OIDC token, other Turnkey enclaves receive the OIDC token as well as:
-- the signed content of the issuer's OpenId configuration. OpenId configuration **must** be hosted under `/.well-known/openid-configuration` for each domain. For Google for example, the issuer configuration is at [`accounts.google.com/.well-known/openid-configuration`](https://accounts.google.com/.well-known/openid-configuration). This JSON document contains, among other thing, a `jwksUri` key. The value for this key is a URL hosting the list of currently-valid OIDC token signers.
-- the signed content of the issuer's `jwksUri` (e.g., for Google, the `jwksUri` is [`googleapis.com/oauth2/v3/cert`](https://www.googleapis.com/oauth2/v3/certs)). This is a list of public keys against which the secure enclave can verify tokens. Note: **these public keys rotate periodically** (every ~6hrs), hence it's not possible to hardcode these public keys in our secure enclave code directly. We have to fetch them dynamically!
+* the signed content of the issuer's OpenId configuration. OpenId configuration **must** be hosted under `/.well-known/openid-configuration` for each domain. For Google for example, the issuer configuration is at [`accounts.google.com/.well-known/openid-configuration`](https://accounts.google.com/.well-known/openid-configuration). This JSON document contains, among other thing, a `jwksUri` key. The value for this key is a URL hosting the list of currently-valid OIDC token signers.
+* the signed content of the issuer's `jwksUri` (e.g., for Google, the `jwksUri` is [`googleapis.com/oauth2/v3/cert`](https://www.googleapis.com/oauth2/v3/certs)). This is a list of public keys against which the secure enclave can verify tokens. Note: **these public keys rotate periodically** (every \~6hrs), hence it's not possible to hardcode these public keys in our secure enclave code directly. We have to fetch them dynamically!
With all of that, an enclave can independently verify an OIDC token without making outbound requests. Once the token is parsed and considered authentic, our enclaves match the `iss`, `aud` and `sub` attributes against the registered OAuth providers on the Turnkey sub-organization. We also check `exp` to make sure the OIDC token is not expired, and the `nonce` attribute (see next section).
## Nonce restrictions in OIDC tokens
-Our [`OAUTH`](/api#tag/Users/operation/Oauth) activity requires 2 parameters minimum:
+Our [`OAUTH`](/api-reference/user-auth/oauth) activity requires 2 parameters minimum:
-- `oidcToken`: the base64 OIDC token
-- `targetPublicKey`: the client-side public key generated by the user
+* `oidcToken`: the base64 OIDC token
+* `targetPublicKey`: the client-side public key generated by the user
In order to prevent OIDC tokens from being used against multiple public keys, our enclaves parse the OIDC token and, as part of the validation logic, enforce that the `nonce` claim is set to `sha256(targetPublicKey)`.
@@ -92,8 +84,8 @@ If your OAuth provider does not allow you to customize `nonce` claims, Turnkey a
[OAuth2.0](https://datatracker.ietf.org/doc/html/rfc6749) is a separate protocol from [OIDC](https://openid.net/specs/openid-connect-core-1_0.html), with distinct goals:
-- "OAuth2.0" is an authorization framework
-- "OIDC" is an authentication framework
+* "OAuth2.0" is an authorization framework
+* "OIDC" is an authentication framework
We chose to name this feature "OAuth" because of the term familiarity: most Turnkey customers will have to setup an "OAuth" app with Google, and the user experience is often referred to as "OAuth" flows regardless of the protocol underneath.
@@ -103,11 +95,11 @@ Below, some details and pointers about specific providers we've worked with befo
### Google
-This provider is extensively tested and supported. We've integrated it in our demo wallet (hosted at https://wallet.tx.xyz), along with Apple and Facebook:
+This provider is extensively tested and supported. We've integrated it in our demo wallet (hosted at [https://wallet.tx.xyz](https://wallet.tx.xyz)), along with Apple and Facebook:
-
- 
-
+
The code is open-source, feel free to [check it out](https://github.com/tkhq/demo-embedded-wallet) for reference. The exact line where the OAuth component is loaded is here: [ui/src/screens/LandingScreen.tsx](https://github.com/tkhq/demo-embedded-wallet/blob/d4ec308e9ce0bf0da7b64da2b39e1a80c077eb82/ui/src/screens/LandingScreen.tsx#L384).
@@ -115,7 +107,7 @@ The main documentation for Google OIDC is available [here](https://github.com/tk
### Apple
-Apple integration is also extensively tested and supported, and is integrated into our demo wallet (hosted at https://wallet.tx.xyz). The code provides an [example component](https://github.com/tkhq/demo-embedded-wallet/blob/bf0e2292cbd2ee9cde6b241591b077fadf7ee71b/src/components/apple-auth.tsx) as well as an [example redirect handler](
- 
-
+
-Code for the [redirect component](https://github.com/tkhq/demo-embedded-wallet/blob/bf0e2292cbd2ee9cde6b241591b077fadf7ee71b/src/components/facebook-auth.tsx), [OAuth callback](
- 
-
+
-# Concepts dictionary
+## Concepts dictionary
-## Organizations
+### Organizations
An organization is a logical grouping of resources like users, policies, and wallets. There are two types of organizations:
@@ -34,44 +22,44 @@ An organization is a logical grouping of resources like users, policies, and wal
| Parent Organization | When you first setup your implementation of Turnkey by signing up on the dashboard you create a parent organization controlled by your business. In most implementations, a top-level organization represents an entire Turnkey-powered implementation. For more information on Turnkey parent organizations [look here](/concepts/organizations). |
| Sub-Organization | A fully segregated organization nested under the parent organization. Parent organizations have read access to all their sub-organizations, but do not have write access. Each sub-organization typically maps to an individual end user in a Turnkey-powered application. Parent organizations can initiate limited actions for sub-organizations that then must be completed by the sub-organization, or without the need for completion by the sub-organization (e.g. `INIT_OTP_AUTH` or `INIT_USER_EMAIL_RECOVERY` require completion by sub-organization, `EMAIL_AUTH` does not). For more information on Turnkey sub-organizations [look here](/concepts/sub-organizations). |
-## Users
+### 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](/concepts/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.
+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](/concepts/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:
| User type | Description |
| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Root Users | The first user(s) created in an organization will have root permissions, meaning they can bypass the policy engine to take any action within that specific organization. This ability can be limited via root quorum, which requires a threshold of root users to access root permissions. For example, if there are five root users and the threshold is three, at least three users must approve an activity for the root quorum threshold to be reached. When you first create a Turnkey organization, your user is automatically created as the sole member of the root quorum by default. |
-| Normal Users | Other than managing their own credentials, non-root users have no permissions unless explicitly granted by [policies](/concepts/policies/overview). By combining non-root users with policies granting permission for specific actions, you can build support for experiences providing [delegated access](/concepts/policies/delegated-access) to business controlled service account. |
+| Normal Users | Other than managing their own credentials, non-root users have no permissions unless explicitly granted by [policies](/concepts/policies/overview). By combining non-root users with policies granting permission for specific actions, you can build support for experiences providing [delegated access](/concepts/policies/delegated-access) to business controlled service account. |
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
+* 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](/concepts/users/introduction).
-## Credentials
+### 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](/concepts/users/credentials).
-## Activities
+### 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).
+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](/developer-reference/api-overview/submissions).
-## Policies
+### 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.
+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](/concepts/policies/overview).
-## Wallets and Private Keys
+### 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:
@@ -82,45 +70,65 @@ Resources used to generate crypto addresses and sign transactions or messages. W
Learn more about leveraging Wallets across different crypto ecosystems on our [Ecosystem Support](/ecosystems/framework) page.
-# Typical implementations
+## Typical implementations
-## Transaction Automation
+### Transaction Automation
Transaction automation entails a business signing transactions on its own behalf. For example, automating payments flows, managing smart contract deployment or programmatically trading in DeFi.
-
- 
-
+
In this setup, the business is in full control of its wallets at all times. This use case typically does not require the use of sub-organizations and everything can be managed from the parent organization. We suggest the following setup:
-- **Root Users:** After initial setup of your parent organization, set a reasonable root quorum (e.g., 2 of 3), attach backup credentials to each user for safekeeping, and only use the root users in a "break glass" scenario.
-- **Service Users:** Create different users for separate services and/or approval workflows. For example, you might have user A that can automatically sign any transaction with Wallet X, but require both user A and user B to approve transactions with Wallet B.
-- **Service Policies:** Set appropriately restrictive policies based on your security needs.
-- **Wallets:** Create separate wallets where differentiated policies are needed, otherwise just leverage multiple wallet accounts within a single wallet.
+* **Root Users:** After initial setup of your parent organization, set a reasonable root quorum (e.g., 2 of 3), attach backup credentials to each user for safekeeping, and only use the root users in a “break glass” scenario.
+* **Service Users:** Create different users for separate services and/or approval workflows. For example, you might have user A that can automatically sign any transaction with Wallet X, but require both user A and user B to approve transactions with Wallet B.
+* **Service Policies:** Set appropriately restrictive policies based on your security needs.
+* **Wallets:** Create separate wallets where differentiated policies are needed, otherwise just leverage multiple wallet accounts within a single wallet.
-## Embedded Wallets
+### Embedded Wallets
Embedded wallets entail a business creating non-custodial wallets controlled by its end users. For example, allowing an end user to create and use a wallet via Web2 authentication methods like email or OAuth.
-
- 
-
+
This is a non-custodial setup where the end user is in control of its wallet at all times. This use case requires the use of sub-organizations which map to an individual end user, and does not require any wallets in the parent organization. The parent organization will be used by your backend service for onboarding new users and initiating certain authentication methods (e.g., email, SMS), while the sub-organizations will be used by the end users for day-to-day signing. We suggest the following setup:
-- **Root Users:** After initial setup of your parent organization, set a reasonable root quorum (e.g., 2 of 3), attach backup credentials to each user for safekeeping, and only use the root users in a "break glass" scenario.
-- **Normal Users:** Create a single service user used for user onboarding and authentication.
-- **Policies:** Set a policy granting the user permission to `CREATE_SUB_ORGANIZATION`, `EMAIL_AUTH`, `OAUTH`, `OTP_AUTH`. For examples of how to create such policies [look here](/concepts/policies/examples).
-- **Sub-organizations:** Create individual sub-organizations for each user that contain a single root user with any relevant credentials, and a single wallet with any relevant wallet accounts.
+* **Root Users:** After initial setup of your parent organization, set a reasonable root quorum (e.g., 2 of 3), attach backup credentials to each user for safekeeping, and only use the root users in a “break glass” scenario.
+* **Normal Users:** Create a single service user used for user onboarding and authentication.
+* **Policies:** Set a policy granting the user permission to `CREATE_SUB_ORGANIZATION`, `EMAIL_AUTH`, `OAUTH`, `OTP_AUTH`. For examples of how to create such policies [look here](/concepts/policies/examples).
+* **Sub-organizations:** Create individual sub-organizations for each user that contain a single root user with any relevant credentials, and a single wallet with any relevant wallet accounts.
For more details on each individual concepts, refer to the pages below:
-
- 
-
+
Almost all actions on Turnkey are implicitly denied by default. There are a few exceptions, however:
-- Root users bypass any policies.
-- All users have implicit GET (read) permissions in their own Organization and any associated Sub-Organizations.
-- All users have implicit permission to change their own credentials.
-- All users have implicit permission to approve an activity if they were included in consensus (i.e., a user specified as part of the consensus required to approve a SIGN_TRANSACTION activity does not need separate, explicit permission to sign transactions).
+* Root users bypass any policies.
+* All users have implicit GET (read) permissions in their own Organization and any associated Sub-Organizations.
+* All users have implicit permission to change their own credentials.
+* All users have implicit permission to approve an activity if they were included in consensus (i.e., a user specified as part of the consensus required to approve a SIGN\_TRANSACTION activity does not need separate, explicit permission to sign transactions).
diff --git a/docs/documentation/concepts/policy-management/Policy-quickstart.md b/concepts/policies/quickstart.mdx
similarity index 64%
rename from docs/documentation/concepts/policy-management/Policy-quickstart.md
rename to concepts/policies/quickstart.mdx
index 648025e7..9d39b53c 100644
--- a/docs/documentation/concepts/policy-management/Policy-quickstart.md
+++ b/concepts/policies/quickstart.mdx
@@ -1,47 +1,48 @@
---
-sidebar_position: 2
-description: Add a new user to your Org and try out the policy engine
-slug: /concepts/policies/quickstart
-sidebar_label: Quickstart
+title: "Policy quickstart"
+description: "This guide will help you add an additional user to your Turnkey organization and set permissions for that user through Policies. Specifically, we will create an API-only user with permissions to sign transactions to an allowlisted address."
+sidebarTitle: "Quickstart"
---
-# Policy quickstart
-
-This guide will help you add an additional user to your Turnkey organization and set permissions for that user through Policies. Specifically, we will create an API-only user with permissions to sign transactions to an allowlisted address.
-
This assumes that you previously completed the [Sign a transaction](/getting-started/quickstart) guide, and thus have already set up:
-- Your Turnkey organization
-- An API key for the Root User
-- A Wallet with an Ethereum account
+* Your Turnkey organization
+* An API key for the Root User
+* A Wallet with an Ethereum account
## Create your new users
New users in your Turnkey organization can be created by navigating to the "Users" tab and clicking "Add User".
-
+
+ 
+
In the create user flow, you have the option to grant API key or web access to your new user. For this example, we're going to create an API-only user.
-
+
+ 
+
Under access types, select "API key". Enter the user name "Policy Test". This will be an API-only user, and therefore an email is not required. Click continue and create a new API key to associate with the user using the following command:
-```shell
+```bash
turnkey generate api-key --organization $ORGANIZATION_ID --key-name policy_test
```
-This will create 2 files, "policy_test.public" and "policy_test.private". Copy the contents of the ".public" file and paste it into "API public key". Finish the create user flow and authenticate. Your new user will appear in the Users table. Note down the user ID as you will use it in the next step.
+This will create 2 files, "policy\_test.public" and "policy\_test.private". Copy the contents of the ".public" file and paste it into "API public key". Finish the create user flow and authenticate. Your new user will appear in the Users table. Note down the user ID as you will use it in the next step.
## Create policies for your new users.
Next we will create a policy to grant permissions to the new user. Navigate to the "Policies" tab and click on "Add new policy".
-
+
+ 
+
Choose a name and note to describe your new policy. Next, enter the following policy, making sure to replace `
- 
-
- 
-
- 
-
-
-
-
-
-
-
-
-Optionally, you may also generate keys using the Turnkey CLI.
-
-
-
-
-
-
-
-
-
-
- 
-
-
-Let's review these steps in detail:
-
-1. User on `yoursite.xyz` clicks "auth", and a new auth UI is shown. We recommend this auth UI be a new hosted page of your site or application, which contains language explaining to the user what steps they will need to take next to successfully authenticate. While the UI is in a loading state your frontend uses [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) to insert a new iframe element:
-
- ```js
- const iframeStamper = new IframeStamper({
- iframeUrl: "https://auth.turnkey.com",
- // Configure how the iframe element is inserted on the page
- iframeContainerId: "your-container",
- iframeElementId: "turnkey-iframe",
- });
-
- // Inserts the iframe in the DOM. This creates the new encryption target key
- const publicKey = await iframeStamper.init();
- ```
-
-2. Your code receives the iframe public key and shows the auth form, and the user enters their email address.
-3. Your app can now create and sign a new `EMAIL_AUTH` activity with the user email and the iframe public key in the parameters. Optional arguments include a custom name for the API key, and a specific duration (denoted in seconds) for it. Note: you'll need to retrieve the sub-organization ID based on the user email.
-4. Email is received by the user.
-5. User copies and pastes their auth code into your app. Remember: this code is an encrypted credential which can only be decrypted within the iframe. In order to enable persistent sessions, save the auth code in local storage:
-
- ```js
- window.localStorage.setItem("BUNDLE", bundle);
- ```
-
- See [Email Customization](#email-customization) below to use a magic link instead of a one time code.
-
-6. Your app injects the auth code into the iframe for decryption:
-
- ```js
- await iframeStamper.injectCredentialBundle(code);
- ```
-
-7. At this point, the user is authenticated!
-
-8. Your app should use [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) to sign a new activity, e.g. `CREATE_WALLET`:
-
- ```js
- // New client instantiated with our iframe stamper
- const client = new TurnkeyClient(
- { baseUrl: "https://api.turnkey.com" },
- iframeStamper,
- );
-
- // Sign and submits the CREATE_WALLET activity
- const response = await client.createWallet({
- type: "ACTIVITY_TYPE_CREATE_WALLET",
- timestampMs: String(Date.now()),
- organizationId: authResponse.organizationId,
- parameters: {
- walletName: "Default Wallet",
- accounts: [
- {
- curve: "CURVE_SECP256K1",
- pathFormat: "PATH_FORMAT_BIP32",
- path: "m/44'/60'/0'/0/0",
- addressFormat: "ADDRESS_FORMAT_ETHEREUM",
- },
- ],
- },
- });
- ```
-
-9. User navigates to a new tab.
-
-10. Because the code was also saved in local storage (step 6), it can be injected into the iframe across different tabs, resulting in a persistent session. See our [Demo Embedded Wallet](https://wallet.tx.xyz) for a [sample implementation](https://github.com/tkhq/demo-embedded-wallet/blob/942ccc97de7f9289892b1714b10f3a21afec71b3/src/providers/auth-provider.tsx#L150-L171), specifically dealing with sharing the iframeStamper across components.
-
- ```js
- const code = window.localStorage.getItem("BUNDLE");
- await iframeStamper.injectCredentialBundle(code);
- ```
-
-11. Again, the user is authenticated, and able to initiate activities!
-
-12. Just like step 8, the iframeStamper can be used to sign another activity.
-
- ```js
- const client = new TurnkeyClient(
- { baseUrl: "https://api.turnkey.com" },
- iframeStamper,
- );
-
- // Sign and submits a SIGN_TRANSACTION activity
- const response = await client.signTransaction({
- type: "ACTIVITY_TYPE_SIGN_TRANSACTION_V2",
- timestampMs: String(Date.now()),
- organizationId: authResponse.organizationId,
- parameters: {
- signWith: "0x...",
- type: "TRANSACTION_TYPE_ETHEREUM",
- unsignedTransaction: "unsigned-tx",
- },
- });
- ```
-
-Congrats! You've succcessfully implemented Email Auth! 🥳
-
-## Integration notes
-
-### Email customization
-
-We offer customization for the following:
-
-- `appName`: the name of the application. This will be used in the email's subject, e.g. `Sign in to ${appName}`
-- `logoUrl`: a link to a PNG with a max width of 340px and max height of 124px
-- `magicLinkTemplate`: a template for the URL to be used in the magic link button, e.g. `https://dapp.xyz/%s`. The auth bundle will be interpolated into the `%s`
-
-```js
-// Sign and submits the EMAIL_AUTH activity
-const response = await client.emailAuth({
- type: "ACTIVITY_TYPE_EMAIL_AUTH",
- timestampMs: String(Date.now()),
- organizationId:
- 
-
- 
-
-
-
-
-Welcome to Turnkey! To make the most out of Turnkey's wallet infrastructure, we've compiled a list of helpful resources for you below.
-
-:::note
-
-Getting ready to launch? Ensure you **double check our [resource limits](/concepts/resource-limits) and [rate limits](/faq#do-you-have-any-rate-limits-in-place-in-your-public-api)** to ensure your implementation will not trigger these limits at production scale.
-For additional pre-launch guidance, **refer to our [Launch Checklist](/getting-started/launch-checklist)** to make sure you're ready to launch safely.
-
-:::
-
-## About
-
-[Turnkey](https://turnkey.com) is highly flexible key management infrastructure,
-purpose-built for security and scale. Our API and open-source SDKs make it easy for you to take your
-product from 0 to 1, and enable developers to create millions of embedded wallets and automate complex onchain transactions.
-
-Whether you're building a DeFi platform, a payments app, an AI agent, or anything requiring a private key,
-Turnkey offers the building blocks to bring your ideas to life.
-
-Our solution covers two main use cases:
-
-Create millions of embedded wallets on behalf of your users for a flawless onboarding and in-app experience.
- -- ⚡ To start building with embedded wallets, check out our demos, kits and - detailed guides: -
- -Automate even the most complex onchain transactions, from staking management to smart contract interactions.
- -- 🔧 To start using Turnkey for onchain automation, check out{" "} - Quickstart,{" "} - - server signing guide - - , and explore our API Reference. -
- -
- 
-
- 
-
rpId?rpId is used in WebAuthn to uniquely identify the server that the passkey is associated with.
-The rpId is typically the effective domain of the web application, which is the domain portion of the URL without any subdomains.
-For example, if your application is hosted at app.example.com, the rpId would typically be example.com.
-This ensures that credentials are scoped to the correct domain and cannot be used by other domains, enhancing security.
+add-passkey.tsx component
- 
-
+
-In this diagram _Host_ represents a standard AWS virtual machine. We run a basic application that receives traffic from the network and calls into the enclave. This creates a layer of insulation from our most secure environment and offers a convenient place to gather metrics and other operational information about the enclaves.
+In this diagram *Host* represents a standard AWS virtual machine. We run a basic application that receives traffic from the network and calls into the enclave. This creates a layer of insulation from our most secure environment and offers a convenient place to gather metrics and other operational information about the enclaves.
-_Enclave_ represents a machine with no external connectivity. The only connection it can have is a virtual serial connection to the host and its own secure co-processor. In AWS this is called the Nitro Security Module (NSM). This runs an instance of Turnkey’s enclave operating system, QuorumOS (QOS), and a secure application running on top of QOS.
+*Enclave* represents a machine with no external connectivity. The only connection it can have is a virtual serial connection to the host and its own secure co-processor. In AWS this is called the Nitro Security Module (NSM). This runs an instance of Turnkey’s enclave operating system, QuorumOS (QOS), and a secure application running on top of QOS.
diff --git a/security/verifiable-data.mdx b/security/verifiable-data.mdx
new file mode 100644
index 00000000..bfe6daa2
--- /dev/null
+++ b/security/verifiable-data.mdx
@@ -0,0 +1,13 @@
+---
+title: "Verifiable Data"
+description: "Enclave applications in Turnkey’s infrastructure are stateless meaning, there is no persistent data held behind the enclave boundary. Instead, data is held in a PostgreSQL instance in our primary AWS account. Before any enclave applications operate on the data in a Turnkey account, it first verifies that that data has been recently notarized by Turnkey’s notarizer. A recent stamp could be the result of an update or initiated by the heartbeat service."
+mode: wide
+---
+
+By verifying the authenticity of data using cryptographic signatures (no passwords!) and timestamping, we enable zero-risk data sharing between these apps and block man-in-the-middle or downgrade attacks. The combination of these features results in a system and an audit trail that is verifiable end-to-end.
+
+The entire Turnkey architecture including this verifiable data flow is described below:
+
+
+ 
+
diff --git a/security/whitepaper.mdx b/security/whitepaper.mdx
new file mode 100644
index 00000000..f791135f
--- /dev/null
+++ b/security/whitepaper.mdx
@@ -0,0 +1,7 @@
+---
+title: "The Turnkey Whitepaper"
+description: "We have published an in-depth whitepaper describing the principles with which we've built Turnkey and explaining in great detail the infrastructure foundations as well as the system architecture underpinning our product."
+mode: wide
+---
+
+Our whitepaper is available online at **[whitepaper.turnkey.com](https://whitepaper.turnkey.com)**.
diff --git a/sidebars.js b/sidebars.js
deleted file mode 100644
index 1688dac4..00000000
--- a/sidebars.js
+++ /dev/null
@@ -1,42 +0,0 @@
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
-
-// @ts-check
-
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
- // Autogenerate sidebars for each documentation section
- sdksSidebar: [
- {
- type: "autogenerated",
- dirName: "sdks",
- },
- ],
- solutionsSidebar: [
- {
- type: "autogenerated",
- dirName: "solutions",
- },
- ],
- documentationSidebar: [
- {
- type: "doc",
- id: "welcome",
- label: "Welcome",
- },
- {
- type: "autogenerated",
- dirName: "documentation",
- },
- ],
-};
-
-module.exports = sidebars;
diff --git a/signing-automation/code-examples/signing-transactions.mdx b/signing-automation/code-examples/signing-transactions.mdx
new file mode 100644
index 00000000..0fbca2a7
--- /dev/null
+++ b/signing-automation/code-examples/signing-transactions.mdx
@@ -0,0 +1,49 @@
+---
+title: "Signing Transactions"
+description: "This is a guide to signing transactions in a server context. While these snippets leverage Ethers, it can be swapped out for other signers in the Viem or Solana contexts. An example for Ethers can be found , and for Viem in the server context. A similar example with Solana can be found ."
+mode: wide
+---
+
+docs directory.
-
- ),
- },
- {
- title: "Powered by React",
- Svg: require("@site/static/img/undraw_docusaurus_react.svg").default,
- description: (
- <>
- Extend or customize your website layout by reusing React. Docusaurus can
- be extended while reusing the same header and footer.
-
- ),
- },
-];
-
-function Feature({ title, Svg, description }: FeatureItem) {
- return (
- {description}
-
- {param.name}
-
-
- {param.type.link ? (
-
-
- {param.type.name}
-
-
- ) : (
-
- {param.type.name}
-
- )}
-
- {isRequired && (
-
- required
-
- )}
- {param?.type?.note && (
- - {children} -
-
+
+
+Here 's how to get started:
+
+