From 80b3cdd128a9cc495a403299a37d17ea036beef6 Mon Sep 17 00:00:00 2001
From: Maidul Islam <maidul98@gmail.com>
Date: Tue, 2 Apr 2024 09:21:32 -0700
Subject: [PATCH] add examples to integration auth docs

---
 backend/src/lib/api-docs/constants.ts                 |  8 ++++----
 .../src/server/routes/v1/integration-auth-router.ts   |  2 +-
 .../endpoints/integrations/create-auth.mdx            |  6 ++++--
 docs/api-reference/endpoints/integrations/create.mdx  | 11 ++++++-----
 4 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/backend/src/lib/api-docs/constants.ts b/backend/src/lib/api-docs/constants.ts
index 0df831526..58931628e 100644
--- a/backend/src/lib/api-docs/constants.ts
+++ b/backend/src/lib/api-docs/constants.ts
@@ -485,14 +485,14 @@ export const INTEGRATION_AUTH = {
     integrationAuthId: "The id of integration authentication object."
   },
   DELETE: {
-    integration: "The slug of integration to be deleted from authorized.",
-    projectId: "The ID of the project to delete integration authorized."
+    integration: "The slug of the integration to be unauthorized.",
+    projectId: "The ID of the project to delete the integration auth from."
   },
   DELETE_BY_ID: {
     integrationAuthId: "The id of integration authentication object to delete."
   },
   CREATE_ACCESS_TOKEN: {
-    workspaceId: "The ID of the project to create integration auth.",
+    workspaceId: "The ID of the project to create the integration auth for.",
     integration: "The slug of integration for the auth object.",
     accessId: "The unique authorized access id of the external integration provider.",
     accessToken: "The unique authorized access token of the external integration provider.",
@@ -501,7 +501,7 @@ export const INTEGRATION_AUTH = {
     refreshToken: "The refresh token for integration authorization."
   },
   LIST_AUTHORIZATION: {
-    workspaceId: "The ID of the project to list integration auth."
+    workspaceId: "The ID of the project to list integration auths for."
   }
 };
 
diff --git a/backend/src/server/routes/v1/integration-auth-router.ts b/backend/src/server/routes/v1/integration-auth-router.ts
index 5fa1a08bc..a68479074 100644
--- a/backend/src/server/routes/v1/integration-auth-router.ts
+++ b/backend/src/server/routes/v1/integration-auth-router.ts
@@ -210,7 +210,7 @@ export const registerIntegrationAuthRouter = async (server: FastifyZodProvider)
     method: "POST",
     onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
-      description: "Create the integration authentication object.",
+      description: "Create the integration authentication object required for syncing secrets.",
       security: [
         {
           bearerAuth: []
diff --git a/docs/api-reference/endpoints/integrations/create-auth.mdx b/docs/api-reference/endpoints/integrations/create-auth.mdx
index 3bec1bddc..5af7a0f9c 100644
--- a/docs/api-reference/endpoints/integrations/create-auth.mdx
+++ b/docs/api-reference/endpoints/integrations/create-auth.mdx
@@ -3,9 +3,11 @@ title: "Create Auth"
 openapi: "POST /api/v1/integration-auth/access-token"
 ---
 
-## Integration Auth Parameters
+## Integration Authentication Parameters
+
+The integration authentication endpoint is generic and can be used for all native integrations. 
+For specific integration parameters for a given service, please review the respective documentation below.
 
-We have a generic endpoints for creating integration auth objects. These are the parameters required for each integration.
 <Tabs>
   <Tab title="AWS Secrets manager">
     <ParamField body="integration" type="string" initialValue="aws-secret-manager" required>
diff --git a/docs/api-reference/endpoints/integrations/create.mdx b/docs/api-reference/endpoints/integrations/create.mdx
index 0572895cf..0992e91b9 100644
--- a/docs/api-reference/endpoints/integrations/create.mdx
+++ b/docs/api-reference/endpoints/integrations/create.mdx
@@ -5,7 +5,8 @@ openapi: "POST /api/v1/integration"
 
 ## Integration Parameters
 
-We have a generic endpoints for creating integration. These are the parameters required for each integration.
+The integration creation endpoint is generic and can be used for all native integrations. 
+For specific integration parameters for a given service, please review the respective documentation below.
 
 <Tabs>
   <Tab title="AWS Secrets manager">
@@ -17,16 +18,16 @@ We have a generic endpoints for creating integration. These are the parameters r
 				Whether the integration should be active or inactive
 		</ParamField>
     <ParamField body="app" type="string" required>
-				The secret name used when saving secret in AWS SSM.
+				The secret name used when saving secret in AWS SSM. Used for naming and can be arbitrary.
 		</ParamField>
     <ParamField body="region" type="string" required>
-				The AWS region of the SSM.
+				The AWS region of the SSM. Example: `us-east-1`
 		</ParamField>
     <ParamField body="sourceEnvironment" type="string" required>
-				The infisical environment for the secrets to be synced.
+				The Infisical environment slug from where secrets will be synced from. Example: `dev`
 		</ParamField>
     <ParamField body="secretPath" type="string" required>
-				The infisical secret path for the secrets to be synced.
+				The Infisical folder path from where secrets will be synced from. Example: `/some/path`. The root of the environment is `/`.
 		</ParamField>
   </Tab>
   <Tab title="GCP Secrets manager">