Add token auth to api reference

backend/src/lib/api-docs/constants.ts

@@ -70,13 +70,13 @@ export const UNIVERSAL_AUTH = {
       "The maximum number of times that an access token can be used; a value of 0 implies infinite number of uses."
   },
   RETRIEVE: {
-    identityId: "The ID of the identity to retrieve."
+    identityId: "The ID of the identity to retrieve the auth method for."
   },
   REVOKE: {
-    identityId: "The ID of the identity to revoke."
+    identityId: "The ID of the identity to revoke the auth method for."
   },
   UPDATE: {
-    identityId: "The ID of the identity to update.",
+    identityId: "The ID of the identity to update the auth method for.",
     clientSecretTrustedIps: "The new list of IPs or CIDR ranges that the Client Secret can be used from.",
     accessTokenTrustedIps: "The new list of IPs or CIDR ranges that access tokens can be used from.",
     accessTokenTTL: "The new lifetime for an access token in seconds.",
@@ -132,7 +132,7 @@ export const AWS_AUTH = {
     accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from."
   },
   UPDATE: {
-    identityId: "The ID of the identity to be updated.",
+    identityId: "The ID of the identity to update the auth method for.",
     allowedPrincipalArns:
       "The new comma-separated list of trusted IAM principal ARNs that are allowed to authenticate with Infisical.",
     allowedAccountIds:
@@ -144,10 +144,10 @@ export const AWS_AUTH = {
     accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from."
   },
   RETRIEVE: {
-    identityId: "The ID of the identity to retrieve."
+    identityId: "The ID of the identity to retrieve the auth method for."
   },
   REVOKE: {
-    identityId: "The ID of the identity to revoke."
+    identityId: "The ID of the identity to revoke the auth method for."
   }
 } as const;
 
@@ -167,7 +167,7 @@ export const AZURE_AUTH = {
     accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
   },
   UPDATE: {
-    identityId: "The ID of the identity to be updated.",
+    identityId: "The ID of the identity to update the auth method for.",
     tenantId: "The new tenant ID for the Azure AD organization.",
     resource: "The new resource URL for the application registered in Azure AD.",
     allowedServicePrincipalIds:
@@ -178,10 +178,10 @@ export const AZURE_AUTH = {
     accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
   },
   RETRIEVE: {
-    identityId: "The ID of the identity to retrieve."
+    identityId: "The ID of the identity to retrieve the auth method for."
   },
   REVOKE: {
-    identityId: "The ID of the identity to revoke."
+    identityId: "The ID of the identity to revoke the auth method for."
   }
 } as const;
 
@@ -203,7 +203,7 @@ export const GCP_AUTH = {
     accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
   },
   UPDATE: {
-    identityId: "The ID of the identity to be updated.",
+    identityId: "The ID of the identity to update the auth method for.",
     allowedServiceAccounts:
       "The new comma-separated list of trusted service account emails corresponding to the GCE resource(s) allowed to authenticate with Infisical.",
     allowedProjects:
@@ -216,10 +216,10 @@ export const GCP_AUTH = {
     accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
   },
   RETRIEVE: {
-    identityId: "The ID of the identity to retrieve."
+    identityId: "The ID of the identity to retrieve the auth method for."
   },
   REVOKE: {
-    identityId: "The ID of the identity to revoke."
+    identityId: "The ID of the identity to revoke the auth method for."
   }
 } as const;
 
@@ -244,7 +244,7 @@ export const KUBERNETES_AUTH = {
     accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
   },
   UPDATE: {
-    identityId: "The ID of the identity to be updated.",
+    identityId: "The ID of the identity to update the auth method for.",
     kubernetesHost: "The new host string, host:port pair, or URL to the base of the Kubernetes API server.",
     caCert: "The new PEM-encoded CA cert for the Kubernetes API server.",
     tokenReviewerJwt:
@@ -260,10 +260,49 @@ export const KUBERNETES_AUTH = {
     accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
   },
   RETRIEVE: {
-    identityId: "The ID of the identity to retrieve."
+    identityId: "The ID of the identity to retrieve the auth method for."
   },
   REVOKE: {
-    identityId: "The ID of the identity to revoke."
+    identityId: "The ID of the identity to revoke the auth method for."
+  }
+} as const;
+
+export const TOKEN_AUTH = {
+  ATTACH: {
+    identityId: "The ID of the identity to attach the configuration onto.",
+    accessTokenTrustedIps: "The IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The maximum number of times that an access token can be used."
+  },
+  UPDATE: {
+    identityId: "The ID of the identity to update the auth method for.",
+    accessTokenTrustedIps: "The new IPs or CIDR ranges that access tokens can be used from.",
+    accessTokenTTL: "The new lifetime for an acccess token in seconds.",
+    accessTokenMaxTTL: "The new maximum lifetime for an acccess token in seconds.",
+    accessTokenNumUsesLimit: "The new maximum number of times that an access token can be used."
+  },
+  RETRIEVE: {
+    identityId: "The ID of the identity to retrieve the auth method for."
+  },
+  REVOKE: {
+    identityId: "The ID of the identity to revoke the auth method for."
+  },
+  GET_TOKENS: {
+    identityId: "The ID of the identity to list token metadata for.",
+    offset: "The offset to start from. If you enter 10, it will start from the 10th token.",
+    limit: "The number of tokens to return"
+  },
+  CREATE_TOKEN: {
+    identityId: "The ID of the identity to create the token for.",
+    name: "The name of the token to create"
+  },
+  UPDATE_TOKEN: {
+    tokenId: "The ID of the token to update metadata for",
+    name: "The name of the token to update to"
+  },
+  REVOKE_TOKEN: {
+    tokenId: "The ID of the token to revoke"
   }
 } as const;
 

backend/src/server/routes/v1/identity-token-auth-router.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import { IdentityAccessTokensSchema, IdentityTokenAuthsSchema } from "@app/db/schemas";
 import { EventType } from "@app/ee/services/audit-log/audit-log-types";
+import { TOKEN_AUTH } from "@app/lib/api-docs";
 import { readLimit, writeLimit } from "@app/server/config/rateLimiter";
 import { verifyAuth } from "@app/server/plugins/auth/verify-auth";
 import { AuthMode } from "@app/services/auth/auth-type";
@@ -23,7 +24,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
         }
       ],
       params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(TOKEN_AUTH.ATTACH.identityId)
       }),
       body: z.object({
         accessTokenTrustedIps: z
@@ -32,7 +33,8 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
           })
           .array()
           .min(1)
-          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }]),
+          .default([{ ipAddress: "0.0.0.0/0" }, { ipAddress: "::/0" }])
+          .describe(TOKEN_AUTH.ATTACH.accessTokenTrustedIps),
         accessTokenTTL: z
           .number()
           .int()
@@ -40,15 +42,17 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
           .refine((value) => value !== 0, {
             message: "accessTokenTTL must have a non zero number"
           })
-          .default(2592000),
+          .default(2592000)
+          .describe(TOKEN_AUTH.ATTACH.accessTokenTTL),
         accessTokenMaxTTL: z
           .number()
           .int()
           .refine((value) => value !== 0, {
             message: "accessTokenMaxTTL must have a non zero number"
           })
-          .default(2592000),
+          .default(2592000)
-        accessTokenNumUsesLimit: z.number().int().min(0).default(0)
+          .describe(TOKEN_AUTH.ATTACH.accessTokenMaxTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).default(0).describe(TOKEN_AUTH.ATTACH.accessTokenNumUsesLimit)
       }),
       response: {
         200: z.object({
@@ -102,7 +106,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
         }
       ],
       params: z.object({
-        identityId: z.string().trim()
+        identityId: z.string().trim().describe(TOKEN_AUTH.UPDATE.identityId)
       }),
       body: z.object({
         accessTokenTrustedIps: z
@@ -111,9 +115,10 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
           })
           .array()
           .min(1)
-          .optional(),
+          .optional()
-        accessTokenTTL: z.number().int().min(0).optional(),
+          .describe(TOKEN_AUTH.UPDATE.accessTokenTrustedIps),
-        accessTokenNumUsesLimit: z.number().int().min(0).optional(),
+        accessTokenTTL: z.number().int().min(0).optional().describe(TOKEN_AUTH.UPDATE.accessTokenTTL),
+        accessTokenNumUsesLimit: z.number().int().min(0).optional().describe(TOKEN_AUTH.UPDATE.accessTokenNumUsesLimit),
         accessTokenMaxTTL: z
           .number()
           .int()
@@ -121,6 +126,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
             message: "accessTokenMaxTTL must have a non zero number"
           })
           .optional()
+          .describe(TOKEN_AUTH.UPDATE.accessTokenMaxTTL)
       }),
       response: {
         200: z.object({
@@ -174,7 +180,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
         }
       ],
       params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(TOKEN_AUTH.RETRIEVE.identityId)
       }),
       response: {
         200: z.object({
@@ -221,7 +227,7 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
         }
       ],
       params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(TOKEN_AUTH.REVOKE.identityId)
       }),
       response: {
         200: z.object({
@@ -253,15 +259,6 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
     }
   });
 
-  // proposed
-  // update token by id: PATCH /token-auth/tokens/:tokenId
-  // revoke token by id: POST /token-auth/tokens/:tokenId/revoke
-
-  // current
-  // revoke token by id: POST /token/revoke-by-id
-
-  // token-auth/identities/:identityId/tokens
-
   server.route({
     method: "POST",
     url: "/token-auth/identities/:identityId/tokens",
@@ -270,17 +267,17 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
     },
     onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
-      description: "Create token for identity with Token Auth configured",
+      description: "Create token for identity with Token Auth",
       security: [
         {
           bearerAuth: []
         }
       ],
       params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(TOKEN_AUTH.CREATE_TOKEN.identityId)
       }),
       body: z.object({
-        name: z.string().optional()
+        name: z.string().optional().describe(TOKEN_AUTH.CREATE_TOKEN.name)
       }),
       response: {
         200: z.object({
@@ -331,18 +328,18 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
     },
     onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
-      description: "Get tokens for identity with Token Auth configured",
+      description: "Get tokens for identity with Token Auth",
       security: [
         {
           bearerAuth: []
         }
       ],
       params: z.object({
-        identityId: z.string()
+        identityId: z.string().describe(TOKEN_AUTH.GET_TOKENS.identityId)
       }),
       querystring: z.object({
-        offset: z.coerce.number().min(0).max(100).default(0),
+        offset: z.coerce.number().min(0).max(100).default(0).describe(TOKEN_AUTH.GET_TOKENS.offset),
-        limit: z.coerce.number().min(1).max(100).default(20)
+        limit: z.coerce.number().min(1).max(100).default(20).describe(TOKEN_AUTH.GET_TOKENS.limit)
       }),
       response: {
         200: z.object({
@@ -383,17 +380,17 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
     },
     onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
-      description: "Update token for identity with Token Auth configured",
+      description: "Update token for identity with Token Auth",
       security: [
         {
           bearerAuth: []
         }
       ],
       params: z.object({
-        tokenId: z.string()
+        tokenId: z.string().describe(TOKEN_AUTH.UPDATE_TOKEN.tokenId)
       }),
       body: z.object({
-        name: z.string().optional()
+        name: z.string().optional().describe(TOKEN_AUTH.UPDATE_TOKEN.name)
       }),
       response: {
         200: z.object({
@@ -436,14 +433,14 @@ export const registerIdentityTokenAuthRouter = async (server: FastifyZodProvider
     },
     onRequest: verifyAuth([AuthMode.JWT, AuthMode.IDENTITY_ACCESS_TOKEN]),
     schema: {
-      description: "Revoke token for identity with Token Auth configured",
+      description: "Revoke token for identity with Token Auth",
       security: [
         {
           bearerAuth: []
         }
       ],
       params: z.object({
-        tokenId: z.string()
+        tokenId: z.string().describe(TOKEN_AUTH.REVOKE_TOKEN.tokenId)
       }),
       response: {
         200: z.object({

docs/api-reference/endpoints/token-auth/attach.mdx

@@ -0,0 +1,4 @@
+---
+title: "Attach"
+openapi: "POST /api/v1/auth/token-auth/identities/{identityId}"
+---

docs/api-reference/endpoints/token-auth/create-token.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create Token"
+openapi: "POST /api/v1/auth/token-auth/identities/{identityId}/tokens"
+---

docs/api-reference/endpoints/token-auth/get-tokens.mdx

@@ -0,0 +1,4 @@
+---
+title: "Get Tokens"
+openapi: "GET /api/v1/auth/token-auth/identities/{identityId}/tokens"
+---

docs/api-reference/endpoints/token-auth/retrieve.mdx

@@ -0,0 +1,4 @@
+---
+title: "Retrieve"
+openapi: "GET /api/v1/auth/token-auth/identities/{identityId}"
+---

docs/api-reference/endpoints/token-auth/revoke-token.mdx

@@ -0,0 +1,4 @@
+---
+title: "Revoke Token"
+openapi: "POST /api/v1/auth/token-auth/tokens/{tokenId}/revoke"
+---

docs/api-reference/endpoints/token-auth/revoke.mdx

@@ -0,0 +1,4 @@
+---
+title: "Revoke"
+openapi: "DELETE /api/v1/auth/token-auth/identities/{identityId}"
+---

docs/api-reference/endpoints/token-auth/update-token.mdx

@@ -0,0 +1,4 @@
+---
+title: "Update Token"
+openapi: "PATCH /api/v1/auth/token-auth/tokens/{tokenId}"
+---

docs/api-reference/endpoints/token-auth/update.mdx

@@ -0,0 +1,4 @@
+---
+title: "Update"
+openapi: "PATCH /api/v1/auth/token-auth/identities/{identityId}"
+---

docs/mint.json

@@ -427,6 +427,19 @@
             "api-reference/endpoints/identities/list"
           ]
         },
+        {
+          "group": "Token Auth",
+          "pages": [
+            "api-reference/endpoints/token-auth/attach",
+            "api-reference/endpoints/token-auth/retrieve",
+            "api-reference/endpoints/token-auth/update",
+            "api-reference/endpoints/token-auth/revoke",
+            "api-reference/endpoints/token-auth/get-tokens",
+            "api-reference/endpoints/token-auth/create-token",
+            "api-reference/endpoints/token-auth/update-token",
+            "api-reference/endpoints/token-auth/revoke-token"
+          ]
+        },
         {
           "group": "Universal Auth",
           "pages": [