openapi and swagger ui improvements and cleanup

server/integrationApiServer.ts

@@ -17,6 +17,7 @@ import fs from "fs";
 import path from "path";
 import { APP_PATH } from "./lib/consts";
 import yaml from "js-yaml";
+import { z } from "zod";
 
 const dev = process.env.ENVIRONMENT !== "prod";
 const externalPort = config.getRawConfig().server.integration_port;
@@ -38,12 +39,24 @@ export function createIntegrationApiServer() {
     apiServer.use(cookieParser());
     apiServer.use(express.json());
 
+    const openApiDocumentation = getOpenApiDocumentation();
+
     apiServer.use(
         "/v1/docs",
         swaggerUi.serve,
-        swaggerUi.setup(getOpenApiDocumentation())
+        swaggerUi.setup(openApiDocumentation)
     );
 
+    // Unauthenticated OpenAPI spec endpoints
+    apiServer.get("/v1/openapi.json", (_req, res) => {
+        res.json(openApiDocumentation);
+    });
+
+    apiServer.get("/v1/openapi.yaml", (_req, res) => {
+        const yamlOutput = yaml.dump(openApiDocumentation);
+        res.type("application/yaml").send(yamlOutput);
+    });
+
     // API routes
     const prefix = `/v1`;
     apiServer.use(logIncomingMiddleware);
@@ -75,16 +88,6 @@ function getOpenApiDocumentation() {
         }
     );
 
-    for (const def of registry.definitions) {
-        if (def.type === "route") {
-            def.route.security = [
-                {
-                    [bearerAuth.name]: []
-                }
-            ];
-        }
-    }
-
     registry.registerPath({
         method: "get",
         path: "/",
@@ -94,6 +97,74 @@ function getOpenApiDocumentation() {
         responses: {}
     });
 
+    registry.registerPath({
+        method: "get",
+        path: "/openapi.json",
+        description: "Get OpenAPI specification as JSON",
+        tags: [],
+        request: {},
+        responses: {
+            "200": {
+                description: "OpenAPI specification as JSON",
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: "object"
+                        }
+                    }
+                }
+            }
+        }
+    });
+
+    registry.registerPath({
+        method: "get",
+        path: "/openapi.yaml",
+        description: "Get OpenAPI specification as YAML",
+        tags: [],
+        request: {},
+        responses: {
+            "200": {
+                description: "OpenAPI specification as YAML",
+                content: {
+                    "application/yaml": {
+                        schema: {
+                            type: "string"
+                        }
+                    }
+                }
+            }
+        }
+    });
+
+    for (const def of registry.definitions) {
+        if (def.type === "route") {
+            def.route.security = [
+                {
+                    [bearerAuth.name]: []
+                }
+            ];
+
+            // Ensure every route has a generic JSON response schema so Swagger UI can render responses
+            const existingResponses = def.route.responses;
+            const hasExistingResponses =
+                existingResponses && Object.keys(existingResponses).length > 0;
+
+            if (!hasExistingResponses) {
+                def.route.responses = {
+                    "*": {
+                        description: "",
+                        content: {
+                            "application/json": {
+                                schema: z.object({})
+                            }
+                        }
+                    }
+                };
+            }
+        }
+    }
+
     const generator = new OpenApiGeneratorV3(registry.definitions);
 
     const generated = generator.generateDocument({

server/openApi.ts

@@ -5,17 +5,20 @@ export const registry = new OpenAPIRegistry();
 export enum OpenAPITags {
     Site = "Site",
     Org = "Organization",
-    Resource = "Resource",
+    PublicResource = "Public Resource",
+    PrivateResource = "Private Resource",
     Role = "Role",
     User = "User",
-    Invitation = "Invitation",
+    Invitation = "User Invitation",
-    Target = "Target",
+    Target = "Resource Target",
     Rule = "Rule",
     AccessToken = "Access Token",
-    Idp = "Identity Provider",
+    GlobalIdp = "Identity Provider (Global)",
+    OrgIdp = "Identity Provider (Organization Only)",
     Client = "Client",
     ApiKey = "API Key",
     Domain = "Domain",
     Blueprint = "Blueprint",
-    Ssh = "SSH"
+    Ssh = "SSH",
+    Logs = "Logs"
 }

server/private/routers/auditLogs/exportAccessAuditLog.ts

@@ -32,7 +32,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/access/export",
     description: "Export the access audit log for an organization as CSV",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryAccessAuditLogsQuery,
         params: queryAccessAuditLogsParams

server/private/routers/auditLogs/exportActionAuditLog.ts

@@ -32,7 +32,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/action/export",
     description: "Export the action audit log for an organization as CSV",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryActionAuditLogsQuery,
         params: queryActionAuditLogsParams

server/private/routers/auditLogs/queryAccessAuditLog.ts

@@ -249,7 +249,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/access",
     description: "Query the access audit log for an organization",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryAccessAuditLogsQuery,
         params: queryAccessAuditLogsParams

server/private/routers/auditLogs/queryActionAuditLog.ts

@@ -160,7 +160,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/action",
     description: "Query the action audit log for an organization",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryActionAuditLogsQuery,
         params: queryActionAuditLogsParams

server/private/routers/billing/getOrgUsage.ts

@@ -31,16 +31,16 @@ const getOrgSchema = z.strictObject({
     orgId: z.string()
 });
 
-registry.registerPath({
+// registry.registerPath({
-    method: "get",
+//     method: "get",
-    path: "/org/{orgId}/billing/usage",
+//     path: "/org/{orgId}/billing/usage",
-    description: "Get an organization's billing usage",
+//     description: "Get an organization's billing usage",
-    tags: [OpenAPITags.Org],
+//     tags: [OpenAPITags.Org],
-    request: {
+//     request: {
-        params: getOrgSchema
+//         params: getOrgSchema
-    },
+//     },
-    responses: {}
+//     responses: {}
-});
+// });
 
 export async function getOrgUsage(
     req: Request,

server/private/routers/orgIdp/createOrgOidcIdp.ts

@@ -52,7 +52,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/idp/oidc",
     description: "Create an OIDC IdP for a specific organization.",
-    tags: [OpenAPITags.Idp, OpenAPITags.Org],
+    tags: [OpenAPITags.OrgIdp],
     request: {
         params: paramsSchema,
         body: {

server/private/routers/orgIdp/deleteOrgIdp.ts

@@ -35,7 +35,7 @@ registry.registerPath({
     method: "delete",
     path: "/org/{orgId}/idp/{idpId}",
     description: "Delete IDP for a specific organization.",
-    tags: [OpenAPITags.Idp, OpenAPITags.Org],
+    tags: [OpenAPITags.OrgIdp],
     request: {
         params: paramsSchema
     },

server/private/routers/orgIdp/getOrgIdp.ts

@@ -50,9 +50,9 @@ async function query(idpId: number, orgId: string) {
 
 registry.registerPath({
     method: "get",
-    path: "/org/:orgId/idp/:idpId",
+    path: "/org/{orgId}/idp/{idpId}",
     description: "Get an IDP by its IDP ID for a specific organization.",
-    tags: [OpenAPITags.Idp, OpenAPITags.Org],
+    tags: [OpenAPITags.OrgIdp],
     request: {
         params: paramsSchema
     },

server/private/routers/orgIdp/listOrgIdps.ts

@@ -67,7 +67,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/idp",
     description: "List all IDP for a specific organization.",
-    tags: [OpenAPITags.Idp, OpenAPITags.Org],
+    tags: [OpenAPITags.OrgIdp],
     request: {
         query: querySchema,
         params: paramsSchema

server/private/routers/orgIdp/updateOrgOidcIdp.ts

@@ -59,7 +59,7 @@ registry.registerPath({
     method: "post",
     path: "/org/{orgId}/idp/{idpId}/oidc",
     description: "Update an OIDC IdP for a specific organization.",
-    tags: [OpenAPITags.Idp, OpenAPITags.Org],
+    tags: [OpenAPITags.OrgIdp],
     request: {
         params: paramsSchema,
         body: {

server/private/routers/resource/getMaintenanceInfo.ts

@@ -52,7 +52,7 @@ registry.registerPath({
     method: "get",
     path: "/maintenance/info",
     description: "Get maintenance information for a resource by domain.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         query: z.object({
             fullDomain: z.string()

server/routers/accessToken/generateAccessToken.ts

@@ -43,7 +43,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/access-token",
     description: "Generate a new access token for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.AccessToken],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.AccessToken],
     request: {
         params: generateAccssTokenParamsSchema,
         body: {

server/routers/accessToken/listAccessTokens.ts

@@ -122,7 +122,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/access-tokens",
     description: "List all access tokens in an organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.AccessToken],
+    tags: [OpenAPITags.AccessToken],
     request: {
         params: z.object({
             orgId: z.string()
@@ -135,8 +135,8 @@ registry.registerPath({
 registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}/access-tokens",
-    description: "List all access tokens in an organization.",
+    description: "List all access tokens for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.AccessToken],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.AccessToken],
     request: {
         params: z.object({
             resourceId: z.number()

server/routers/apiKeys/createOrgApiKey.ts

@@ -37,7 +37,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/api-key",
     description: "Create a new API key scoped to the organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.ApiKey],
+    tags: [OpenAPITags.ApiKey],
     request: {
         params: paramsSchema,
         body: {

server/routers/apiKeys/deleteApiKey.ts

@@ -18,7 +18,7 @@ registry.registerPath({
     method: "delete",
     path: "/org/{orgId}/api-key/{apiKeyId}",
     description: "Delete an API key.",
-    tags: [OpenAPITags.Org, OpenAPITags.ApiKey],
+    tags: [OpenAPITags.ApiKey],
     request: {
         params: paramsSchema
     },

server/routers/apiKeys/listApiKeyActions.ts

@@ -48,7 +48,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/api-key/{apiKeyId}/actions",
     description: "List all actions set for an API key.",
-    tags: [OpenAPITags.Org, OpenAPITags.ApiKey],
+    tags: [OpenAPITags.ApiKey],
     request: {
         params: paramsSchema,
         query: querySchema

server/routers/apiKeys/listOrgApiKeys.ts

@@ -52,7 +52,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/api-keys",
     description: "List all API keys for an organization",
-    tags: [OpenAPITags.Org, OpenAPITags.ApiKey],
+    tags: [OpenAPITags.ApiKey],
     request: {
         params: paramsSchema,
         query: querySchema

server/routers/apiKeys/setApiKeyActions.ts

@@ -25,7 +25,7 @@ registry.registerPath({
     path: "/org/{orgId}/api-key/{apiKeyId}/actions",
     description:
         "Set actions for an API key. This will replace any existing actions.",
-    tags: [OpenAPITags.Org, OpenAPITags.ApiKey],
+    tags: [OpenAPITags.ApiKey],
     request: {
         params: paramsSchema,
         body: {

server/routers/auditLogs/exportRequestAuditLog.ts

@@ -20,7 +20,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/request",
     description: "Query the request audit log for an organization",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryAccessAuditLogsQuery.omit({
             limit: true,

server/routers/auditLogs/queryRequestAnalytics.ts

@@ -151,7 +151,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/analytics",
     description: "Query the request audit analytics for an organization",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryAccessAuditLogsQuery,
         params: queryRequestAuditLogsParams

server/routers/auditLogs/queryRequestAuditLog.ts

@@ -182,7 +182,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/logs/request",
     description: "Query the request audit log for an organization",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Logs],
     request: {
         query: queryAccessAuditLogsQuery,
         params: queryRequestAuditLogsParams

server/routers/blueprints/applyJSONBlueprint.ts

@@ -20,7 +20,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/blueprint",
     description: "Apply a base64 encoded JSON blueprint to an organization",
-    tags: [OpenAPITags.Org, OpenAPITags.Blueprint],
+    tags: [OpenAPITags.Blueprint],
     request: {
         params: applyBlueprintParamsSchema,
         body: {

server/routers/blueprints/applyYAMLBlueprint.ts

@@ -43,7 +43,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/blueprint",
     description: "Create and apply a YAML blueprint to an organization",
-    tags: [OpenAPITags.Org, OpenAPITags.Blueprint],
+    tags: [OpenAPITags.Blueprint],
     request: {
         params: applyBlueprintParamsSchema,
         body: {

server/routers/blueprints/getBlueprint.ts

@@ -53,7 +53,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/blueprint/{blueprintId}",
     description: "Get a blueprint by its blueprint ID.",
-    tags: [OpenAPITags.Org, OpenAPITags.Blueprint],
+    tags: [OpenAPITags.Blueprint],
     request: {
         params: getBlueprintSchema
     },

server/routers/blueprints/listBlueprints.ts

@@ -67,7 +67,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/blueprints",
     description: "List all blueprints for a organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.Blueprint],
+    tags: [OpenAPITags.Blueprint],
     request: {
         params: z.object({
             orgId: z.string()

server/routers/client/createClient.ts

@@ -48,7 +48,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/client",
     description: "Create a new client for an organization.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.Client],
     request: {
         params: createClientParamsSchema,
         body: {

server/routers/client/createUserClient.ts

@@ -49,7 +49,7 @@ registry.registerPath({
     path: "/org/{orgId}/user/{userId}/client",
     description:
         "Create a new client for a user and associate it with an existing olm.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org, OpenAPITags.User],
+    tags: [OpenAPITags.Client],
     request: {
         params: paramsSchema,
         body: {

server/routers/client/getClient.ts

@@ -243,7 +243,7 @@ registry.registerPath({
     path: "/org/{orgId}/client/{niceId}",
     description:
         "Get a client by orgId and niceId. NiceId is a readable ID for the site and unique on a per org basis.",
-    tags: [OpenAPITags.Org, OpenAPITags.Site],
+    tags: [OpenAPITags.Site],
     request: {
         params: z.object({
             orgId: z.string(),

server/routers/client/listClients.ts

@@ -237,7 +237,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/clients",
     description: "List all clients for an organization.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.Client],
     request: {
         query: listClientsSchema,
         params: listClientsParamsSchema

server/routers/client/listUserDevices.ts

@@ -256,7 +256,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/user-devices",
     description: "List all user devices for an organization.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.Client],
     request: {
         query: listUserDevicesSchema,
         params: listUserDevicesParamsSchema

server/routers/client/pickClientDefaults.ts

@@ -23,7 +23,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/pick-client-defaults",
     description: "Return pre-requisite data for creating a client.",
-    tags: [OpenAPITags.Client, OpenAPITags.Site],
+    tags: [OpenAPITags.Client],
     request: {
         params: pickClientDefaultsSchema
     },

server/routers/domain/listDomains.ts

@@ -59,7 +59,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/domains",
     description: "List all domains for a organization.",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Domain],
     request: {
         params: z.object({
             orgId: z.string()

server/routers/idp/createIdpOrgPolicy.ts

@@ -27,7 +27,7 @@ registry.registerPath({
     method: "put",
     path: "/idp/{idpId}/org/{orgId}",
     description: "Create an IDP policy for an existing IDP on an organization.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema,
         body: {

server/routers/idp/createOidcIdp.ts

@@ -37,7 +37,7 @@ registry.registerPath({
     method: "put",
     path: "/idp/oidc",
     description: "Create an OIDC IdP.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         body: {
             content: {

server/routers/idp/deleteIdp.ts

@@ -21,7 +21,7 @@ registry.registerPath({
     method: "delete",
     path: "/idp/{idpId}",
     description: "Delete IDP.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema
     },

server/routers/idp/deleteIdpOrgPolicy.ts

@@ -19,7 +19,7 @@ registry.registerPath({
     method: "delete",
     path: "/idp/{idpId}/org/{orgId}",
     description: "Create an OIDC IdP for an organization.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema
     },

server/routers/idp/getIdp.ts

@@ -34,7 +34,7 @@ registry.registerPath({
     method: "get",
     path: "/idp/{idpId}",
     description: "Get an IDP by its IDP ID.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema
     },

server/routers/idp/listIdpOrgPolicies.ts

@@ -48,7 +48,7 @@ registry.registerPath({
     method: "get",
     path: "/idp/{idpId}/org",
     description: "List all org policies on an IDP.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema,
         query: querySchema

server/routers/idp/listIdps.ts

@@ -58,7 +58,7 @@ registry.registerPath({
     method: "get",
     path: "/idp",
     description: "List all IDP in the system.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         query: querySchema
     },

server/routers/idp/updateIdpOrgPolicy.ts

@@ -26,7 +26,7 @@ registry.registerPath({
     method: "post",
     path: "/idp/{idpId}/org/{orgId}",
     description: "Update an IDP org policy.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema,
         body: {

server/routers/idp/updateOidcIdp.ts

@@ -42,7 +42,7 @@ registry.registerPath({
     method: "post",
     path: "/idp/{idpId}/oidc",
     description: "Update an OIDC IdP.",
-    tags: [OpenAPITags.Idp],
+    tags: [OpenAPITags.GlobalIdp],
     request: {
         params: paramsSchema,
         body: {

server/routers/resource/addEmailToResourceWhitelist.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/whitelist/add",
     description: "Add a single email to the resource whitelist.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: addEmailToResourceWhitelistParamsSchema,
         body: {

server/routers/resource/addRoleToResource.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/roles/add",
     description: "Add a single role to a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Role],
     request: {
         params: addRoleToResourceParamsSchema,
         body: {

server/routers/resource/addUserToResource.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/users/add",
     description: "Add a single user to a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.User],
     request: {
         params: addUserToResourceParamsSchema,
         body: {

server/routers/resource/createResource.ts

@@ -79,7 +79,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/resource",
     description: "Create a resource.",
-    tags: [OpenAPITags.Org, OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: createResourceParamsSchema,
         body: {

server/routers/resource/createResourceRule.ts

@@ -31,7 +31,7 @@ registry.registerPath({
     method: "put",
     path: "/resource/{resourceId}/rule",
     description: "Create a resource rule.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Rule],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Rule],
     request: {
         params: createResourceRuleParamsSchema,
         body: {

server/routers/resource/deleteResource.ts

@@ -22,7 +22,7 @@ registry.registerPath({
     method: "delete",
     path: "/resource/{resourceId}",
     description: "Delete a resource.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: deleteResourceSchema
     },

server/routers/resource/deleteResourceRule.ts

@@ -19,7 +19,7 @@ registry.registerPath({
     method: "delete",
     path: "/resource/{resourceId}/rule/{ruleId}",
     description: "Delete a resource rule.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Rule],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Rule],
     request: {
         params: deleteResourceRuleSchema
     },

server/routers/resource/getResource.ts

@@ -54,7 +54,7 @@ registry.registerPath({
     path: "/org/{orgId}/resource/{niceId}",
     description:
         "Get a resource by orgId and niceId. NiceId is a readable ID for the resource and unique on a per org basis.",
-    tags: [OpenAPITags.Org, OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: z.object({
             orgId: z.string(),
@@ -68,7 +68,7 @@ registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}",
     description: "Get a resource by resourceId.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: z.object({
             resourceId: z.number()

server/routers/resource/getResourceWhitelist.ts

@@ -31,7 +31,7 @@ registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}/whitelist",
     description: "Get the whitelist of emails for a specific resource.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: getResourceWhitelistSchema
     },

server/routers/resource/listAllResourceNames.ts

@@ -33,7 +33,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/resources-names",
     description: "List all resource names for an organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: z.object({
             orgId: z.string()

server/routers/resource/listResourceRoles.ts

@@ -35,7 +35,7 @@ registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}/roles",
     description: "List all roles for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Role],
     request: {
         params: listResourceRolesSchema
     },

server/routers/resource/listResourceRules.ts

@@ -56,7 +56,7 @@ registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}/rules",
     description: "List rules for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Rule],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Rule],
     request: {
         params: listResourceRulesParamsSchema,
         query: listResourceRulesSchema

server/routers/resource/listResourceUsers.ts

@@ -38,7 +38,7 @@ registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}/users",
     description: "List all users for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.User],
     request: {
         params: listResourceUsersSchema
     },

server/routers/resource/listResources.ts

@@ -225,7 +225,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/resources",
     description: "List resources for an organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: z.object({
             orgId: z.string()

server/routers/resource/removeEmailFromResourceWhitelist.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/whitelist/remove",
     description: "Remove a single email from the resource whitelist.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: removeEmailFromResourceWhitelistParamsSchema,
         body: {

server/routers/resource/removeRoleFromResource.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/roles/remove",
     description: "Remove a single role from a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Role],
     request: {
         params: removeRoleFromResourceParamsSchema,
         body: {

server/routers/resource/removeUserFromResource.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/users/remove",
     description: "Remove a single user from a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.User],
     request: {
         params: removeUserFromResourceParamsSchema,
         body: {

server/routers/resource/setResourceHeaderAuth.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     path: "/resource/{resourceId}/header-auth",
     description:
         "Set or update the header authentication for a resource. If user and password is not provided, it will remove the header authentication.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: setResourceAuthMethodsParamsSchema,
         body: {

server/routers/resource/setResourcePassword.ts

@@ -25,7 +25,7 @@ registry.registerPath({
     path: "/resource/{resourceId}/password",
     description:
         "Set the password for a resource. Setting the password to null will remove it.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: setResourceAuthMethodsParamsSchema,
         body: {

server/routers/resource/setResourcePincode.ts

@@ -29,7 +29,7 @@ registry.registerPath({
     path: "/resource/{resourceId}/pincode",
     description:
         "Set the PIN code for a resource. Setting the PIN code to null will remove it.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: setResourceAuthMethodsParamsSchema,
         body: {

server/routers/resource/setResourceRoles.ts

@@ -23,7 +23,7 @@ registry.registerPath({
     path: "/resource/{resourceId}/roles",
     description:
         "Set roles for a resource. This will replace all existing roles.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Role],
     request: {
         params: setResourceRolesParamsSchema,
         body: {

server/routers/resource/setResourceUsers.ts

@@ -23,7 +23,7 @@ registry.registerPath({
     path: "/resource/{resourceId}/users",
     description:
         "Set users for a resource. This will replace all existing users.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.User],
     request: {
         params: setUserResourcesParamsSchema,
         body: {

server/routers/resource/setResourceWhitelist.ts

@@ -32,7 +32,7 @@ registry.registerPath({
     path: "/resource/{resourceId}/whitelist",
     description:
         "Set email whitelist for a resource. This will replace all existing emails.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: setResourceWhitelistParamsSchema,
         body: {

server/routers/resource/updateResource.ts

@@ -136,7 +136,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}",
     description: "Update a resource.",
-    tags: [OpenAPITags.Resource],
+    tags: [OpenAPITags.PublicResource],
     request: {
         params: updateResourceParamsSchema,
         body: {

server/routers/resource/updateResourceRule.ts

@@ -38,7 +38,7 @@ registry.registerPath({
     method: "post",
     path: "/resource/{resourceId}/rule/{ruleId}",
     description: "Update a resource rule.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Rule],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Rule],
     request: {
         params: updateResourceRuleParamsSchema,
         body: {

server/routers/role/createRole.ts

@@ -45,7 +45,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/role",
     description: "Create a role.",
-    tags: [OpenAPITags.Org, OpenAPITags.Role],
+    tags: [OpenAPITags.Role],
     request: {
         params: createRoleParamsSchema,
         body: {

server/routers/role/listRoles.ts

@@ -7,7 +7,7 @@ import { and, eq, inArray, sql } from "drizzle-orm";
 import { ActionsEnum } from "@server/auth/actions";
 import { NextFunction, Request, Response } from "express";
 import createHttpError from "http-errors";
-import { z } from "zod";
+import { object, z } from "zod";
 import { fromError } from "zod-validation-error";
 
 const listRolesParamsSchema = z.strictObject({
@@ -64,7 +64,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/roles",
     description: "List roles.",
-    tags: [OpenAPITags.Org, OpenAPITags.Role],
+    tags: [OpenAPITags.Role],
     request: {
         params: listRolesParamsSchema,
         query: listRolesSchema

server/routers/site/createSite.ts

@@ -58,7 +58,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/site",
     description: "Create a new site.",
-    tags: [OpenAPITags.Site, OpenAPITags.Org],
+    tags: [OpenAPITags.Site],
     request: {
         params: createSiteParamsSchema,
         body: {

server/routers/site/getSite.ts

@@ -51,7 +51,7 @@ registry.registerPath({
     path: "/org/{orgId}/site/{niceId}",
     description:
         "Get a site by orgId and niceId. NiceId is a readable ID for the site and unique on a per org basis.",
-    tags: [OpenAPITags.Org, OpenAPITags.Site],
+    tags: [OpenAPITags.Site],
     request: {
         params: z.object({
             orgId: z.string(),

server/routers/site/listSites.ts

@@ -180,7 +180,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/sites",
     description: "List all sites in an organization",
-    tags: [OpenAPITags.Org, OpenAPITags.Site],
+    tags: [OpenAPITags.Site],
     request: {
         params: listSitesParamsSchema,
         query: listSitesSchema

server/routers/site/pickSiteDefaults.ts

@@ -35,7 +35,7 @@ registry.registerPath({
     path: "/org/{orgId}/pick-site-defaults",
     description:
         "Return pre-requisite data for creating a site, such as the exit node, subnet, Newt credentials, etc.",
-    tags: [OpenAPITags.Org, OpenAPITags.Site],
+    tags: [OpenAPITags.Site],
     request: {
         params: z.object({
             orgId: z.string()

server/routers/siteResource/addClientToSiteResource.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     path: "/site-resource/{siteResourceId}/clients/add",
     description:
         "Add a single client to a site resource. Clients with a userId cannot be added.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Client],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Client],
     request: {
         params: addClientToSiteResourceParamsSchema,
         body: {

server/routers/siteResource/addRoleToSiteResource.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     method: "post",
     path: "/site-resource/{siteResourceId}/roles/add",
     description: "Add a single role to a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Role],
     request: {
         params: addRoleToSiteResourceParamsSchema,
         body: {

server/routers/siteResource/addUserToSiteResource.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     method: "post",
     path: "/site-resource/{siteResourceId}/users/add",
     description: "Add a single user to a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.User],
     request: {
         params: addUserToSiteResourceParamsSchema,
         body: {

server/routers/siteResource/createSiteResource.ts

@@ -114,7 +114,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/site-resource",
     description: "Create a new site resource.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: createSiteResourceParamsSchema,
         body: {

server/routers/siteResource/deleteSiteResource.ts

@@ -23,7 +23,7 @@ registry.registerPath({
     method: "delete",
     path: "/site-resource/{siteResourceId}",
     description: "Delete a site resource.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: deleteSiteResourceParamsSchema
     },

server/routers/siteResource/getSiteResource.ts

@@ -65,7 +65,7 @@ registry.registerPath({
     method: "get",
     path: "/site-resource/{siteResourceId}",
     description: "Get a specific site resource by siteResourceId.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: z.object({
             siteResourceId: z.number(),
@@ -80,7 +80,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/site/{siteId}/resource/nice/{niceId}",
     description: "Get a specific site resource by niceId.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: z.object({
             niceId: z.string(),

server/routers/siteResource/listAllSiteResourcesByOrg.ts

@@ -112,7 +112,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/site-resources",
     description: "List all site resources for an organization.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: listAllSiteResourcesByOrgParamsSchema,
         query: listAllSiteResourcesByOrgQuerySchema

server/routers/siteResource/listSiteResourceClients.ts

@@ -39,7 +39,7 @@ registry.registerPath({
     method: "get",
     path: "/site-resource/{siteResourceId}/clients",
     description: "List all clients for a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Client],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Client],
     request: {
         params: listSiteResourceClientsSchema
     },

server/routers/siteResource/listSiteResourceRoles.ts

@@ -40,7 +40,7 @@ registry.registerPath({
     method: "get",
     path: "/site-resource/{siteResourceId}/roles",
     description: "List all roles for a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Role],
     request: {
         params: listSiteResourceRolesSchema
     },

server/routers/siteResource/listSiteResourceUsers.ts

@@ -43,7 +43,7 @@ registry.registerPath({
     method: "get",
     path: "/site-resource/{siteResourceId}/users",
     description: "List all users for a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.User],
     request: {
         params: listSiteResourceUsersSchema
     },

server/routers/siteResource/listSiteResources.ts

@@ -58,7 +58,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/site/{siteId}/resources",
     description: "List site resources for a site.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: listSiteResourcesParamsSchema,
         query: listSiteResourcesQuerySchema

server/routers/siteResource/removeClientFromSiteResource.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     path: "/site-resource/{siteResourceId}/clients/remove",
     description:
         "Remove a single client from a site resource. Clients with a userId cannot be removed.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Client],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Client],
     request: {
         params: removeClientFromSiteResourceParamsSchema,
         body: {

server/routers/siteResource/removeRoleFromSiteResource.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     method: "post",
     path: "/site-resource/{siteResourceId}/roles/remove",
     description: "Remove a single role from a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Role],
     request: {
         params: removeRoleFromSiteResourceParamsSchema,
         body: {

server/routers/siteResource/removeUserFromSiteResource.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     method: "post",
     path: "/site-resource/{siteResourceId}/users/remove",
     description: "Remove a single user from a site resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.User],
     request: {
         params: removeUserFromSiteResourceParamsSchema,
         body: {

server/routers/siteResource/setSiteResourceClients.ts

@@ -30,7 +30,7 @@ registry.registerPath({
     path: "/site-resource/{siteResourceId}/clients",
     description:
         "Set clients for a site resource. This will replace all existing clients. Clients with a userId cannot be added.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Client],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Client],
     request: {
         params: setSiteResourceClientsParamsSchema,
         body: {

server/routers/siteResource/setSiteResourceRoles.ts

@@ -31,7 +31,7 @@ registry.registerPath({
     path: "/site-resource/{siteResourceId}/roles",
     description:
         "Set roles for a site resource. This will replace all existing roles.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Role],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.Role],
     request: {
         params: setSiteResourceRolesParamsSchema,
         body: {

server/routers/siteResource/setSiteResourceUsers.ts

@@ -31,7 +31,7 @@ registry.registerPath({
     path: "/site-resource/{siteResourceId}/users",
     description:
         "Set users for a site resource. This will replace all existing users.",
-    tags: [OpenAPITags.Resource, OpenAPITags.User],
+    tags: [OpenAPITags.PrivateResource, OpenAPITags.User],
     request: {
         params: setSiteResourceUsersParamsSchema,
         body: {

server/routers/siteResource/updateSiteResource.ts

@@ -121,7 +121,7 @@ registry.registerPath({
     method: "post",
     path: "/site-resource/{siteResourceId}",
     description: "Update a site resource.",
-    tags: [OpenAPITags.Client, OpenAPITags.Org],
+    tags: [OpenAPITags.PrivateResource],
     request: {
         params: updateSiteResourceParamsSchema,
         body: {

server/routers/target/createTarget.ts

@@ -58,7 +58,7 @@ registry.registerPath({
     method: "put",
     path: "/resource/{resourceId}/target",
     description: "Create a target for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Target],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Target],
     request: {
         params: createTargetParamsSchema,
         body: {

server/routers/target/listTargets.ts

@@ -88,7 +88,7 @@ registry.registerPath({
     method: "get",
     path: "/resource/{resourceId}/targets",
     description: "List targets for a resource.",
-    tags: [OpenAPITags.Resource, OpenAPITags.Target],
+    tags: [OpenAPITags.PublicResource, OpenAPITags.Target],
     request: {
         params: listTargetsParamsSchema,
         query: listTargetsSchema

server/routers/user/createOrgUser.ts

@@ -37,7 +37,7 @@ registry.registerPath({
     method: "put",
     path: "/org/{orgId}/user",
     description: "Create an organization user.",
-    tags: [OpenAPITags.User, OpenAPITags.Org],
+    tags: [OpenAPITags.User],
     request: {
         params: paramsSchema,
         body: {

server/routers/user/getOrgUser.ts

@@ -55,7 +55,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/user/{userId}",
     description: "Get a user in an organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.User],
+    tags: [OpenAPITags.User],
     request: {
         params: getOrgUserParamsSchema
     },

server/routers/user/getOrgUserByUsername.ts

@@ -35,7 +35,7 @@ registry.registerPath({
     path: "/org/{orgId}/user-by-username",
     description:
         "Get a user in an organization by username. When idpId is not passed, only internal users are searched (username is globally unique for them). For external (OIDC) users, pass idpId to search by username within that identity provider.",
-    tags: [OpenAPITags.Org, OpenAPITags.User],
+    tags: [OpenAPITags.User],
     request: {
         params: getOrgUserByUsernameParamsSchema,
         query: getOrgUserByUsernameQuerySchema

server/routers/user/inviteUser.ts

@@ -44,7 +44,7 @@ registry.registerPath({
     method: "post",
     path: "/org/{orgId}/create-invite",
     description: "Invite a user to join an organization.",
-    tags: [OpenAPITags.Org],
+    tags: [OpenAPITags.Invitation],
     request: {
         params: inviteUserParamsSchema,
         body: {

server/routers/user/listInvitations.ts

@@ -54,7 +54,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/invitations",
     description: "List invitations in an organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.Invitation],
+    tags: [OpenAPITags.Invitation],
     request: {
         params: listInvitationsParamsSchema,
         query: listInvitationsQuerySchema

server/routers/user/listUsers.ts

@@ -69,7 +69,7 @@ registry.registerPath({
     method: "get",
     path: "/org/{orgId}/users",
     description: "List users in an organization.",
-    tags: [OpenAPITags.Org, OpenAPITags.User],
+    tags: [OpenAPITags.User],
     request: {
         params: listUsersParamsSchema,
         query: listUsersSchema