Merge pull-request #69

docs/FAQ.md

@@ -35,24 +35,7 @@ Think about Turnkey API keys as an access-gating mechanism to Turnkey functional
 
 ### Are there limits on how many resources I can create, or activities I can execute?
 
-We have limits on the number of resources within a single organization to avoid performance slowdowns. You can scale your organizational resources beyond these limits via [sub-organizations](./getting-started/Sub-Organizations.md). You can create an unlimited number of sub-organizations within a single organization.
-
-Currently, the resource limits within a single organization are as follows:
-
-| Resource                       | Maximum number allowed |
-| :----------------------------- | :--------------------- |
-| Private keys                   | 1,000                  |
-| Wallets                        | 100                    |
-| Users                          | 100                    |
-| Policies                       | 100                    |
-| Invitations                    | 100                    |
-| Tags                           | 100                    |
-| Authenticators per user        | 10                     |
-| API keys per user (long-lived) | 10                     |
-| API keys per user (expiring)   | 10                     |
-| Sub-Organizations              | unlimited              |
-
-If you are approaching any of these limits in your implementation and require support, reach out to the Turnkey team (<[email protected]>).
+See [resource limits](./getting-started/resource-limits).
 
 ### Do you have any rate limits in place in your public API?
 

docs/getting-started/email-auth.md

@@ -8,14 +8,18 @@ slug: /getting-started/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).
 
+#### 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.
+
 ## 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`: 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)
 - `apiKeyName`: an optional name for the API Key. If none is provided, we will default to `Email Auth - <Timestamp>`
-- `expirationSeconds`: an optional window (in seconds) indicating how long the API Key should last. Default to 30 minutes.
+- `expirationSeconds`: an optional window (in seconds) indicating how long the API Key should last. Default to 15 minutes.
 - `emailCustomization`: optional parameters for customizing emails. If not provided, use defaults. This is currently a WIP. 🚧
 
 This activity generates a new API key pair (an "auth credential"), saves the public key in organization data under the target user, and sends an email with the encrypted auth credential:
@@ -58,7 +62,7 @@ Similar to email recovery, depending on your threat model, it may be unacceptabl
 
 If you _never_ want to have email auth enabled for sub-organizations, our `CREATE_SUB_ORGANIZATION` activity takes a `disableEmailAuth` boolean in its parameters. Set it to `true` and the sub-organization will be created without the organization feature.
 
-## Cryptographic details
+## Mechanism and cryptographic details
 
 Note: if the following section looks familiar, it is! It shares the same cryptographic innerworkings as Email Recovery.
 

docs/getting-started/resource-limits.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 9
+description: Organization resource limits
+slug: /getting-started/resource-limits
+---
+
+# Resource Limits
+
+We have limits on the number of resources within a single organization to avoid performance slowdowns. You can scale your organizational resources beyond these limits via [sub-organizations](./Sub-Organizations.md). You can create an unlimited number of sub-organizations within a single organization.
+
+Currently, the resource limits within a single organization are as follows:
+
+| Resource                       | Maximum number allowed |
+| :----------------------------- | :--------------------- |
+| Private keys                   | 1,000                  |
+| Wallets                        | 100                    |
+| Users                          | 100                    |
+| Policies                       | 100                    |
+| Invitations                    | 100                    |
+| Tags                           | 100                    |
+| Authenticators per user        | 10                     |
+| API keys per user (long-lived) | 10                     |
+| API keys per user (expiring)   | 10                     |
+| Sub-Organizations              | unlimited              |
+
+If you are approaching any of these limits in your implementation and require support, reach out to the Turnkey team (<[email protected]>).

docs/user-management/Best-practices.md

@@ -1,9 +1,9 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 description: Best practices as you set up users and policies
-slug: /managing-users/best-practices
+slug: /users/best-practices
 ---
-# User and policy best practices
+# Best practices
 
 This page describes some best practices to consider as you set up users and policies while getting ready for production.
 

docs/user-management/Introduction.md

@@ -1,40 +1,16 @@
 ---
 sidebar_position: 1
 description: Learn about Users on Turnkey
-slug: /managing-users/introduction
+slug: /users/introduction
 ---
-# Introduction to users
+# Introduction
 
 Turnkey Users are resources within an Organization. Their attributes are:
 
 - UUID: a globally unique ID (e.g. `fc6372d1-723d-4f7e-8554-dc3a212e4aec`), used as a unique identifier for a User in the context of Policies or User Tags, or Quorums.
 - Name and email
-- Access type: whether a user has access to Turnkey via our dashboard (`ACCESS_TYPE_WEB`), API (`ACCESS_TYPE_API`) or both (`ACCESS_TYPE_ALL`)
 - Authenticators: a list of authenticators (see below for information)
 - API key: a list of API keys (see below for information)
 - User tags: a list of User Tag UUIDs
 
 A **user belongs to one organization**, and one organization can have many (**up to 100**) users. If you need to create more users, consider using Sub-Organizations.
-
-## User Credentials
-
-Credentials represent ways for Users to authenticate to Turnkey. All Turnkey Credentials are held by you, the end-user. Turnkey only keeps **public keys**. At the moment, Turnkey supports 2 types of Credentials:
-
-- Authenticators
-- API Keys
-
-### 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.
-
-When logging into Turnkey, you'll be prompted for a signature with a registered device. This signature is then verified to grant dashboard access. To avoid repeated signatures, Turnkey's dashboard uses session cookies for read traffic. However, all write actions require an authenticator signature.
-
-### API Keys
-
-Turnkey API requests are authenticated with API key signature. When you generate an API key (either through our CLI or through our dashboard), you generate a P-256 key pair. Turnkey keeps the public key, and you hold the private key.
-
-SDK requests or requests made with our CLI use the private API key to sign requests. Turnkey's public API expects all requests (to get data or to submit activities) to be signed.
-
-## Access Type
-
-An API user can only authenticate with API keys, a web-only user can only authenticate with Authenticators, and a web+api user can authenticate with either. There's currently no restrictions on the number of authenticators or API keys attached to a user.

docs/user-management/Root-quorum.md

@@ -1,7 +1,7 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 description: Learn about the root quorum and how to manage it
-slug: /managing-users/root-quorum
+slug: /users/root-quorum
 ---
 # Root quorum
 

docs/user-management/_category_.json

@@ -1,9 +1,9 @@
 {
-  "label": "Managing users",
+  "label": "Users",
   "position": 3,
   "collapsed": false,
   "link": {
     "type": "generated-index",
-    "description": "Managing organization users."
+    "description": "Organization users."
   }
 }

docs/user-management/credentials.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 2
+description: Learn about user credentials and authentication on Turnkey
+slug: /users/credentials
+---
+
+# Credentials
+
+Credentials represent ways for Users to authenticate to Turnkey. All Turnkey Credentials are held by you, the end-user. Turnkey only keeps **public keys**. At the moment, Turnkey supports 2 types of Credentials:
+
+- Authenticators
+- API Keys
+
+### 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.
+
+When logging into Turnkey, you'll be prompted for a signature with a registered device. This signature is then verified to grant dashboard access. To avoid repeated signatures, Turnkey's dashboard uses session cookies for read traffic. However, all write actions require an authenticator signature.
+
+### API Keys
+
+Turnkey API requests are authenticated with API key signatures. When you generate an API key (either through our CLI or through our dashboard), you generate a P-256 key pair. Turnkey keeps the public key, and you hold the private key.
+
+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.