email auth edits

docs/getting-started/email-auth.md

@@ -6,15 +6,15 @@ slug: /getting-started/email-auth
 
 # Email Auth
 
-Email Auth enables a user to authenticate their Turnkey account via email. In this process, the user is granted an expiring API key that is held in local storage. This expiring API key can be used by the user to access their wallet, similar to a session key. An example utilizing Email Auth for an organization can be found in our SDK repo [here](https://github.com/tkhq/sdk/tree/main/examples/email-auth).
+Email Auth enables a user to authenticate their Turnkey account via email. In this process, the user is granted an expiring API key that is stored in memory within an iframe. This expiring API key can then be used by the user to access their wallet, similar to a session key. An example utilizing Email Auth for an organization can be found in our SDK repo [here](https://github.com/tkhq/sdk/tree/main/examples/email-auth).
 
 #### Mechanism
 
-In short, Email Auth is built on top of the expiring API keys primitive: email is simply the mechanism through which the API key credential is safely delivered. Once the credential is live on the client side (within the context of an iframe), it is readily available to stamp (authenticate) requests. See the [cryptographic details](#cryptographic-details) section for more info.
+In short, Email Auth is built with expiring API keys as the foundation: email is simply the mechanism through which the API key credential is safely delivered. Once the credential is live on the client side (within the context of an iframe), it is readily available to stamp (authenticate) requests. See the [cryptographic details](#cryptographic-details) section for more info on how we achieve secure delivery.
 
 ## User Experience
 
-Email auth starts with a new activity posted to Turnkey. This activity has the type `ACTIVITY_TYPE_EMAIL_AUTH` and takes the following as parameters:
+Email Auth starts with a new activity posted to Turnkey. This activity has the type `ACTIVITY_TYPE_EMAIL_AUTH` and takes the following as parameters:
 
 - `email`: the email of the user who would like to authenticate. This email must be the email already attached to the user in organization data (i.e., previously approved by the user). This prevents malicious account takeover. If you try to pass a different email address, the activity will fail.
 - `targetPublicKey`: the public key to which the auth credential is encrypted (more on this later)
@@ -32,7 +32,7 @@ This activity generates a new API key pair (an "auth credential"), saves the pub
     />
 </p>
 
-Calling email auth requires proper permissions via policies or being a parent organization. See [Authorization](#authorization) for more details.
+Calling Email Auth requires proper permissions via policies or being a parent organization. See [Authorization](#authorization) for more details.
 
 ## Authorization
 

docs/user-management/Best-practices.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 description: Best practices as you set up users and policies
 slug: /users/best-practices
 ---

docs/user-management/Root-quorum.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 description: Learn about the root quorum and how to manage it
 slug: /users/root-quorum
 ---

docs/user-management/credentials.md

@@ -11,6 +11,8 @@ Credentials represent ways for Users to authenticate to Turnkey. All Turnkey Cre
 - Authenticators
 - API Keys
 
+Note that every Turnkey user needs at least one long-lived credential (a passkey, or non-expiring API key). This is to prevent users from getting locked out of their accounts. The exception is if the user belongs to a suborg, and [Email Recovery](../getting-started/email-recovery.md) is enabled for that suborg.
+
 ### Authenticators
 
 Turnkey uses [Webauthn](https://www.w3.org/TR/webauthn-2/) for authentication into its dashboard (no passwords!). Authenticators on Turnkey represent a Webauthn device registered on Turnkey.
@@ -24,7 +26,3 @@ Turnkey API requests are authenticated with API key signatures. When you generat
 Requests made via SDK or CLI use the private API key to sign requests. Turnkey's public API expects all requests (e.g. to get data or to submit activities) to be signed.
 
 See our [API reference](./api#tag/API-Keys/operation/CreateApiKeys) for how to programmatically create API keys.
-
-#### Session keys
-
-Turnkey session keys are built atop API keys, with one key difference: they have an expiration date. This date can be specified using the `expirationSeconds` parameter within a `CREATE_API_KEYS` request. Session keys are an effective way for an application to authenticate requests on behalf of a user for a specific duration.

docs/user-management/sessions.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+description: Learn about user sessions on Turnkey
+slug: /users/sessions
+---
+
+# Sessions and session keys
+
+Turnkey session keys are a flavor of API keys, with one key distinction: they expire. The expiration can be specified using the `expirationSeconds` parameter within a `CREATE_API_KEYS` request (or any other request which includes the creation of an API key). Expiring API keys, or session keys, are an effective way for an application to authenticate requests on behalf of a user for a specific duration.
+
+Session keys can be used to create a user session, in which a user is able to perform multiple actions in succession (e.g. signing a series of transactions). This is the basis of [Email Auth](../getting-started/email-auth.md), a Turnkey primitive through which a user can utilize their email to be granted a session of custom duration. See the [integration guide](../integration-guides/email-auth-for-sub-organizations.md) for how to get started with Email Auth.