structure, markup, and mechanics

bc-devrev · bc-devrev · commit 6b2f3e9c171e · 2024-06-18T15:01:26.000-07:00
diff --git a/fern/docs/pages/references/keyrings/developer_keyring.mdx b/fern/docs/pages/references/keyrings/developer_keyring.mdx
@@ -1,42 +1,38 @@
-Developer Keyrings - For Development Workflows
+In addition to keyrings for storing user or organization credentials, DevRev also offers a special type called developer keyrings. These keyrings cater specifically to developers during the snap-in creation process.
 
-While the previous pages focused on keyrings used to store user or organization credentials, DevRev also offers a special type called developer keyrings. These keyrings cater specifically to developers during the creation process.
+Unlike other keyrings that store user credentials, developer keyrings are designed to hold sensitive information needed by the developer during development and execution of any particular task. These secrets are provided by you, the developer, during the creation of a snap-in version. They are not exposed to users and are stored separately from the snap-in itself.
 
-* Unlike other keyrings that store user credentials, developer keyrings are designed to hold sensitive information needed by the developer during development and execution of any particular task.
-* These secrets are provided by you, the developer, during the creation of a snap_in version. They are not exposed to users and are stored separately from the snap_in itself.
+## Snap-in secrets
 
-**Types of Developer Keyrings:**
+A `snap_in_secret` is a simple way to store any plain text secret your snap_in requires. It's ideal for sensitive information that doesn't require complex formatting.
 
-* **snap_in_secret:** This is a simple way to store any plain text secret your snap_in requires. It's ideal for sensitive information that doesn't require complex formatting.
-* **oauth_secret:** This type of keyring is specifically designed to store OAuth client credentials securely. It allows you to define two separate fields:
-  * client_id: The client ID provided by the OAuth provider.
-  * client_secret: The client secret provided by the OAuth provider.
+To create a snap-in secret in the UI, go to the snap-in page **Connection** tab and find the `snap_in_secret` keyring type.
 
-Creating a Developer Keyring
+To create a snap-in secret with the CLI, ruun the following command:
 
-To create a developer keyring, follow these steps:
+```bash
+echo \"[<SECRET>]\" | devrev developer_keyring create snap-in-secret <KEYRING NAME>
+```
+
+## OAuth secrets
 
-1. creating a keyring type of snap_in_secret:
-   * Using the UI:
-     Navigate to the Snap-in page, click on the connection tab, and then find the snap_in_secret keyring type.
-   * Using the CLI:
-     Run the following command:
-     ```bash
-     echo \"[SECRET]\" | devrev developer_keyring create snap-in-secret <name of the keyring>
-     ```
-2. creating a keyring type of oauth_secret:
-    * Using the CLI:
-      Run the following command:
-      ```bash
-      echo '{"client_id":"[CLIENT_ID]","client_secret":"[CLIENT_SECRET]"}' | devrev developer_keyring create oauth-secret <NAME>
-      ```
-Once you've created the keyring, you can use it in your snap_in by referencing the keyring name in the snap_in manifest file.
+An `oauth_secret` is specifically designed to store OAuth client credentials securely. It allows you to define two separate fields:
 
-**Declaring Developer Keyrings in the Snap-in Manifest:**
+  * `client_id`: The client ID provided by the OAuth provider.
+  * `client_secret`: The client secret provided by the OAuth provider.
 
-This section explains how to declare a developer keyring in your snap-in manifest. Developer keyrings provide a secure way to store sensitive information needed by your snap-in, such as OAuth client credentials.
+To create an OAuth secret with the CLI, run the following command:
+
+```bash
+echo '{"client_id":"[<CLIENT ID>]","client_secret":"[<CLIENT SECRET>]"}' | devrev developer_keyring create oauth-secret <KEYRING NAME>
+```
+
+## Developer keyrings in the snap-in manifest
+
+Once you've created the keyring, you can use it in your snap-in by referencing the keyring name in the snap-in manifest file.
 
 Syntax:
+
 ```yaml
   developer_keyrings:
     - name: <name of the keyring>
diff --git a/fern/docs/pages/references/keyrings/introduction.mdx b/fern/docs/pages/references/keyrings/introduction.mdx
@@ -1,18 +1,10 @@
-**Keyrings: Securely Connecting Your Snap-in to External Services**
-
 Keyrings provide a secure way to manage credentials for external services used within your DevRev snap-in. This eliminates the need to store sensitive information like passwords or access tokens directly in your code or configuration files, improving overall security.
 
-**Why are Keyrings Important?**
-
 Traditionally, developers might store these credentials directly in their snap-in's code. This poses a significant security risk. If someone gains access to your code, they could also steal these sensitive credentials.
-Keyrings provide a secure alternative. By storing credentials separately from your code, you ensure they remain hidden and inaccessible even if the code is compromised. This strengthens the overall security of your snap-in.
-
 
-
-**How Keyrings Work**
+Keyrings provide a secure alternative. By storing credentials separately from your code, you ensure they remain hidden and inaccessible even if the code is compromised. This strengthens the overall security of your snap-in.
 
 Imagine you're building a DevRev snap-in that helps manage your marketing campaigns across different platforms. This snap-in might need to connect to various external services like Facebook Ads, Mailchimp, and a project management tool like Asana.
-Traditionally, you might embed the API keys or access tokens for these services directly in your snap-in's code. This poses a security risk because anyone with access to the code could potentially steal these credentials.
 
 Here's where DevRev keyrings come in:
 
@@ -22,17 +14,18 @@ When your snap-in needs to interact with a specific service, it retrieves the ne
 
 Think of keyrings as secure vaults within your snap-in, acting as a middleman between your snap-in and the external services it connects to. This ensures both security and a smooth user experience during installation.
 
-**Supported Credential Types:**
+## Supported credential types
 
 * **OAuth:** Streamline connections with popular services like Slack and Jira using pre-defined OAuth keyrings.
-* **Secrets (PATs, JSON):** Store various secret configurations, including Personal Access Tokens (PATs) and JSON Web Tokens (JWTs) for broader service integrations.
+* **Secrets:** Store various secret configurations, including personal access tokens (PATs) and JSON web tokens (JWTs) for broader service integrations.
+
+## Access levels
 
-**Access Levels:**
+- **User level:** Securely store credentials specific to individual users, allowing them to connect their own accounts to external services through your snap-in.
+- **Organization level:** Share credentials across your organization for access to a single, shared account for an external service.
 
-* **User Level:** Securely store credentials specific to individual users, allowing them to connect their own accounts to external services through your snap-in.
-* **Organization Level:** Share credentials across your organization for access to a single, shared account for an external service.
+## Syntax
 
-**Syntax:**
 ```yaml
 keyrings:
   organization:
diff --git a/fern/docs/pages/references/keyrings/oauth_config.mdx b/fern/docs/pages/references/keyrings/oauth_config.mdx
@@ -1,21 +1,30 @@
-OAuth Configurations - Securely Storing Access Tokens
-
 OAuth (Open Authorization) is a widely adopted standard for authorization that allows users to grant access to their accounts on one service (like Google or GitHub) to another application (like your DevRev snap-in) without needing to share their passwords directly. This approach enhances security and user convenience.
 
-For a comprehensive understanding of the OAuth specification, refer to the official documentation: [OAuth 2.0](https://oauth.net/2/).
+For comprehensive information about the OAuth specification, refer to the official documentation: [OAuth 2.0](https://oauth.net/2/).
+
+## Using OAuth keyrings
 
-Utilizing OAuth Keyrings:
+1. **Define the keyring:** Within your snap-in manifest, define a keyring specifically for OAuth credentials. DevRev offers pre-defined keyring types for popular services like Slack or Jira, simplifying the process.
 
-- **Define the Keyring:** Within your snap-in manifest, define a keyring specifically for OAuth credentials. DevRev offers pre-defined keyring types for popular services like Slack or Jira, simplifying the process.
+2. **Provide credentials:** During development, you'll provide your developer keyring of type `oauth-secret` which contains client ID and client secret for the chosen service within the keyring definition. These credentials are securely stored and not distributed with your published snap-in.
 
-- **Provide Credentials:** During development, you'll provide your developer keyring of type `oauth-secret` which contains client ID and client secret for the chosen service within the keyring definition. These credentials are securely stored and not distributed with your published snap-in.
+3. **OAuth flow:** When your snap-in needs to access user data from the external service, it initiates the OAuth flow. This typically involves redirecting the user to the service's login page and then back to your snap-in after successful authorization.
 
-- **OAuth Flow:** When your snap-in needs to access user data from the external service, it initiates the OAuth flow. This typically involves redirecting the user to the service's login page and then back to your snap-in after successful authorization.
+4. **Access tokens:** Upon successful authorization, the service provides your snap-in with an access token. This token is used to access user data on the service's behalf without requiring the user's password again.
 
-- **Access Tokens:** Upon successful authorization, the service provides your snap-in with an access token. This token is used to access user data on the service's behalf without requiring the user's password again.
+5. **Refreshing tokens:** A key benefit of using keyrings for OAuth is that they can handle refreshing access tokens automatically. Most OAuth implementations issue a refresh token alongside the access token. This refresh token can be used to obtain a new access token before the current one expires.
 
-- **Refreshing Tokens:** A key benefit of using keyrings for OAuth is that they can handle refreshing access tokens automatically. Most OAuth implementations issue a refresh token alongside the access token. This refresh token can be used to obtain a new access token before the current one expires.
+### Keywords
+
+The supported keywords that can be dynamically inserted into URLs, headers, and query parameters within your custom keyring type configuration.
+    - `ACCESS_TOKEN`: The access token obtained during the OAuth flow.
+    - `REFRESH_TOKEN`: The refresh token obtained during the OAuth flow.
+    - `CLIENT_ID`: The client ID obtained from the OAuth client credentials.
+    - `CLIENT_SECRET`: The client secret obtained from the OAuth client credentials.
+    - `SCOPE`: The scope of the OAuth flow.
+    - `API_KEY`: The API key obtained from the basic flow.
 
+### Syntax
 
 ```yaml
 developer_keyrings:
@@ -87,16 +96,4 @@ keyring_types:
         <param_name>: <param_value>
 ```
 
-<Callout intent="note"> 
-
-**Supported keywords in keyring_type configuration**:
-The supported keywords that can be dynamically inserted into URLs, headers, and query parameters within your custom keyring type configuration.
-    - **[ACCESS_TOKEN]**: The access token obtained during the OAuth flow.
-    - **[REFRESH_TOKEN]**: The refresh token obtained during the OAuth flow.
-    - **[CLIENT_ID]**: The client ID obtained from the OAuth client credentials.
-    - **[CLIENT_SECRET]**: The client secret obtained from the OAuth client credentials.
-    - **[SCOPE]**: The scope of the OAuth flow.
-    - **[API_KEY]**: The API key obtained from the basic flow.
- </Callout>
-
 For examples of how to use keyrings in your snap-in, refer to the [Keyring API documentation](https://github.com/devrev/snap-in-examples/tree/main/13-keyring-type).
diff --git a/fern/docs/pages/references/keyrings/secret_config.mdx b/fern/docs/pages/references/keyrings/secret_config.mdx
@@ -1,18 +1,12 @@
-Secret Configurations - Securely Storing Credentials (PATs, JSON)
+Secret configurations are a type of keyring well-suited for storing credentials like personal access tokens (PATs) and multi-field tokens (often stored in JSON format).
 
-Keyrings offer various mechanisms for storing sensitive information required by your snap-in to connect with external services. This page focuses on secret configurations, a type of keyring well-suited for storing credentials like Personal Access Tokens (PATs) and Multi-field Tokens (often stored in JSON format).
+## PAT keyrings
 
-- **Personal Access Tokens (PATs)** are API keys generated by many services like GitHub, GitLab, or cloud platforms like AWS or Azure. These tokens grant programmatic access to specific resources or functionalities within the service, on behalf of a user.
-    - Imagine your snap-in needs to interact with a user's GitHub repository. Instead of embedding the user's username and password directly in your code (a major security risk!), you can leverage secret configurations. During installation, your snap-in can prompt the user to provide their PAT for GitHub access. This PAT is then securely stored within a secret configuration keyring. Whenever your snap-in needs to interact with the user's GitHub repository, it retrieves the PAT from the keyring and uses it for authorization.
+_Personal access tokens (PATs)_ are API keys generated by services like GitHub or GitLab, or by cloud platforms like AWS or Azure. These tokens grant programmatic access to specific resources or functionalities within the service, on behalf of a user.
 
+Imagine your snap-in needs to interact with a user's GitHub repository. Instead of embedding the user's username and password directly in your code (a major security risk!), you can leverage secret configurations. During installation, your snap-in can prompt the user to provide their PAT for GitHub access. This PAT is then securely stored within a secret configuration keyring. Whenever your snap-in needs to interact with the user's GitHub repository, it retrieves the PAT from the keyring and uses it for authorization.
 
-- **Multi-field tokens** are a broader category that often come in JSON format (JavaScript Object Notation). They can contain various fields with different pieces of information needed for authorization with a service.
-  - Some services might use custom authentication mechanisms that require more than just a single token value. These services might provide credentials in JSON format, containing fields like access keys, secret keys, or expiration times. Secret configurations offer a secure way to store these multi-field tokens within your snap-in.
-
-
-**1. Demonstrating PAT Keyrings in the Snap-in Manifest:**
-
-To use secret configurations in your snap-in, you need to declare them in your snap-in's manifest file (`manifest.yaml`). Here's a syntax of how you can declare a secret configuration keyring:
+To use secret configurations in your snap-in, you need to declare them in your snap-in's manifest file. Here's a syntax of how you can declare a secret configuration keyring:
 
 ```yaml
 keyrings:
@@ -29,12 +23,16 @@ keyrings:
       types:
         - snap-in-secret
 ```
-DevRev offers pre-defined keyring types for simplified credential management. The snap-in-secret type is a versatile option for storing Personal Access Tokens (PATs) that need to be shared across your organization within your snap-in. This pre-defined type eliminates the need to create a custom keyring type specifically for PATs.
 
+DevRev offers pre-defined keyring types for simplified credential management. This pre-defined type eliminates the need to create a custom keyring type specifically for PATs.
 
-**2. Demonstrating Multi-field Keyrings in the Snap-in Manifest:**
+## Multi-field keyrings
 
-To use secret configurations in your snap-in, you need to declare them in your snap-in's manifest file (`manifest.yaml`). Here's a syntax of how you can declare a secret configuration keyring:
+_Multi-field tokens_ are a broader category that often come in JSON format. They can contain various fields with different pieces of information needed for authorization with a service.
+
+Some services might use custom authentication mechanisms that require more than just a single token value. These services might provide credentials in JSON format, containing fields like access keys, secret keys, or expiration times. Secret configurations offer a secure way to store these multi-field tokens within your snap-in.
+
+To use secret configurations in your snap-in, you need to declare them in your snap-in's manifest file. Here's a syntax of how you can declare a secret configuration keyring:
 
 ```yaml
 keyrings:
@@ -77,11 +75,11 @@ keyring_types:
             <param_name>: <param_value> # optional: query parameters to be included in the verification request.
 ```
 
-**3. Demonstrating Secret Configuration to achieve Basic Authentication in the Snap-in Manifest:**
+## Basic authentication with keyrings
 
-For a more in-depth understanding of Basic Authentication, you can refer to the Uncyclopedia article: [Basic authentication on Uncyclopedia](https://en.wikipedia.org/wiki/Basic_access_authentication). This resource provides detailed information about the protocol and its potential security considerations.
+For more information about basic authentication, you can refer to the Uncyclopedia article: [Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). This resource provides detailed information about the protocol and its potential security considerations.
 
-Here's an syntax of how you can define a secret configuration keyring for Basic Authentication in your snap-in's manifest file (`manifest.yaml`):
+Here's an syntax of how you can define a secret configuration keyring for basic authentication in your snap-in's manifest file:
 
 ```yaml
 keyrings:
@@ -126,13 +124,12 @@ keyring_types:
 ```
 The secret_transform field is intended for more advanced scenarios where the secret needs to be transformed before use. For example, it could be used to hash a password before storing it within the keyring. The jq query provided in this field will be applied to the secret data before it is stored.
 
-<Callout intent="note">
+### Keyring types
+
+The supported keywords that can be dynamically inserted into URLs, headers, and query parameters within your custom keyring type configuration.
 
-    **Supported keywords in keyring_type configuration**:
-    The supported keywords that can be dynamically inserted into URLs, headers, and query parameters within your custom keyring type configuration.
-    - **[API_KEY]**: The API key obtained from the secret configuration.
-    - **[SUBDOMAIN]**: The subdomain obtained from the secret configuration.
-    - **[FIELD_ID]**: The field ID obtained from the secret configuration.
-</Callout>
+- `API_KEY`: The API key obtained from the secret configuration.
+- `SUBDOMAIN`: The subdomain obtained from the secret configuration.
+- `FIELD_ID`: The field ID obtained from the secret configuration.
 
 For examples of how to use keyrings in your snap-in, refer to the [Keyring API documentation](https://github.com/devrev/snap-in-examples/tree/main/13-keyring-type).
diff --git a/fern/versions/public.yml b/fern/versions/public.yml
