Skip to content

Commit 237b590

Browse files
author
Lasim
committed
feat(backend): enhance API documentation for authentication methods
1 parent 215c5ee commit 237b590

File tree

5 files changed

+180
-30
lines changed

5 files changed

+180
-30
lines changed

‎services/backend/api-spec.json‎

Lines changed: 52 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7528,10 +7528,13 @@
75287528
"tags": [
75297529
"Teams"
75307530
],
7531-
"description": "Retrieves all teams that the currently authenticated user belongs to, including their role, admin status, ownership status, and member count.",
7531+
"description": "Retrieves all teams that the currently authenticated user belongs to, including their role, admin status, ownership status, and member count. Supports both cookie-based authentication (for web users) and OAuth2 Bearer token authentication (for CLI users). Requires teams:read scope for OAuth2 access.",
75327532
"security": [
75337533
{
75347534
"cookieAuth": []
7535+
},
7536+
{
7537+
"bearerAuth": []
75357538
}
75367539
],
75377540
"responses": {
@@ -7649,7 +7652,42 @@
76497652
"application/json": {
76507653
"schema": {
76517654
"schema": {
7652-
"description": "Unauthorized - Authentication required",
7655+
"description": "Unauthorized - Authentication required or invalid token",
7656+
"type": "object",
7657+
"properties": {
7658+
"success": {
7659+
"default": false,
7660+
"description": "Indicates if the operation was successful (false for errors)",
7661+
"type": "boolean"
7662+
},
7663+
"error": {
7664+
"description": "Error message",
7665+
"type": "string"
7666+
},
7667+
"details": {
7668+
"description": "Additional error details (validation errors)",
7669+
"type": "array",
7670+
"items": {}
7671+
}
7672+
},
7673+
"required": [
7674+
"success",
7675+
"error"
7676+
],
7677+
"additionalProperties": false
7678+
},
7679+
"components": {}
7680+
}
7681+
}
7682+
}
7683+
},
7684+
"403": {
7685+
"description": "Default Response",
7686+
"content": {
7687+
"application/json": {
7688+
"schema": {
7689+
"schema": {
7690+
"description": "Forbidden - Insufficient permissions or scope",
76537691
"type": "object",
76547692
"properties": {
76557693
"success": {
@@ -7722,7 +7760,7 @@
77227760
"tags": [
77237761
"Teams"
77247762
],
7725-
"description": "Retrieves a specific team by its ID with the current user's role and permissions within that team. User must be a member of the team.",
7763+
"description": "Retrieves a specific team by its ID with the current user's role and permissions within that team. User must be a member of the team. Supports both cookie-based authentication (for web users) and OAuth2 Bearer token authentication (for CLI users). Requires teams:read scope for OAuth2 access.",
77267764
"parameters": [
77277765
{
77287766
"schema": {
@@ -7736,6 +7774,9 @@
77367774
"security": [
77377775
{
77387776
"cookieAuth": []
7777+
},
7778+
{
7779+
"bearerAuth": []
77397780
}
77407781
],
77417782
"responses": {
@@ -7850,7 +7891,7 @@
78507891
"application/json": {
78517892
"schema": {
78527893
"schema": {
7853-
"description": "Unauthorized - Authentication required",
7894+
"description": "Unauthorized - Authentication required or invalid token",
78547895
"type": "object",
78557896
"properties": {
78567897
"success": {
@@ -7885,7 +7926,7 @@
78857926
"application/json": {
78867927
"schema": {
78877928
"schema": {
7888-
"description": "Forbidden - Insufficient permissions",
7929+
"description": "Forbidden - Insufficient permissions or scope",
78897930
"type": "object",
78907931
"properties": {
78917932
"success": {
@@ -12223,10 +12264,13 @@
1222312264
"tags": [
1222412265
"MCP Categories"
1222512266
],
12226-
"description": "Retrieve all available MCP server categories for organization. No Content-Type header required for this GET request.",
12267+
"description": "Retrieve all available MCP server categories for organization. Supports both cookie-based authentication (for web users) and OAuth2 Bearer token authentication (for CLI users). Requires mcp:categories:read scope for OAuth2 access. No Content-Type header required for this GET request.",
1222712268
"security": [
1222812269
{
1222912270
"cookieAuth": []
12271+
},
12272+
{
12273+
"bearerAuth": []
1223012274
}
1223112275
],
1223212276
"responses": {
@@ -12308,7 +12352,7 @@
1230812352
"application/json": {
1230912353
"schema": {
1231012354
"schema": {
12311-
"description": "Unauthorized - Authentication required",
12355+
"description": "Unauthorized - Authentication required or invalid token",
1231212356
"type": "object",
1231312357
"properties": {
1231412358
"success": {
@@ -12336,7 +12380,7 @@
1233612380
"application/json": {
1233712381
"schema": {
1233812382
"schema": {
12339-
"description": "Forbidden - Insufficient permissions",
12383+
"description": "Forbidden - Insufficient permissions or scope",
1234012384
"type": "object",
1234112385
"properties": {
1234212386
"success": {

‎services/backend/api-spec.yaml‎

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5172,9 +5172,12 @@ paths:
51725172
- Teams
51735173
description: Retrieves all teams that the currently authenticated user belongs
51745174
to, including their role, admin status, ownership status, and member
5175-
count.
5175+
count. Supports both cookie-based authentication (for web users) and
5176+
OAuth2 Bearer token authentication (for CLI users). Requires teams:read
5177+
scope for OAuth2 access.
51765178
security:
51775179
- cookieAuth: []
5180+
- bearerAuth: []
51785181
responses:
51795182
"200":
51805183
description: Default Response
@@ -5260,7 +5263,32 @@ paths:
52605263
application/json:
52615264
schema:
52625265
schema:
5263-
description: Unauthorized - Authentication required
5266+
description: Unauthorized - Authentication required or invalid token
5267+
type: object
5268+
properties:
5269+
success:
5270+
default: false
5271+
description: Indicates if the operation was successful (false for errors)
5272+
type: boolean
5273+
error:
5274+
description: Error message
5275+
type: string
5276+
details:
5277+
description: Additional error details (validation errors)
5278+
type: array
5279+
items: {}
5280+
required:
5281+
- success
5282+
- error
5283+
additionalProperties: false
5284+
components: {}
5285+
"403":
5286+
description: Default Response
5287+
content:
5288+
application/json:
5289+
schema:
5290+
schema:
5291+
description: Forbidden - Insufficient permissions or scope
52645292
type: object
52655293
properties:
52665294
success:
@@ -5311,6 +5339,9 @@ paths:
53115339
- Teams
53125340
description: Retrieves a specific team by its ID with the current user's role
53135341
and permissions within that team. User must be a member of the team.
5342+
Supports both cookie-based authentication (for web users) and OAuth2
5343+
Bearer token authentication (for CLI users). Requires teams:read scope
5344+
for OAuth2 access.
53145345
parameters:
53155346
- schema:
53165347
type: string
@@ -5319,6 +5350,7 @@ paths:
53195350
required: true
53205351
security:
53215352
- cookieAuth: []
5353+
- bearerAuth: []
53225354
responses:
53235355
"200":
53245356
description: Default Response
@@ -5402,7 +5434,7 @@ paths:
54025434
application/json:
54035435
schema:
54045436
schema:
5405-
description: Unauthorized - Authentication required
5437+
description: Unauthorized - Authentication required or invalid token
54065438
type: object
54075439
properties:
54085440
success:
@@ -5427,7 +5459,7 @@ paths:
54275459
application/json:
54285460
schema:
54295461
schema:
5430-
description: Forbidden - Insufficient permissions
5462+
description: Forbidden - Insufficient permissions or scope
54315463
type: object
54325464
properties:
54335465
success:
@@ -8427,10 +8459,14 @@ paths:
84278459
summary: List all MCP server categories
84288460
tags:
84298461
- MCP Categories
8430-
description: Retrieve all available MCP server categories for organization. No
8431-
Content-Type header required for this GET request.
8462+
description: Retrieve all available MCP server categories for organization.
8463+
Supports both cookie-based authentication (for web users) and OAuth2
8464+
Bearer token authentication (for CLI users). Requires
8465+
mcp:categories:read scope for OAuth2 access. No Content-Type header
8466+
required for this GET request.
84328467
security:
84338468
- cookieAuth: []
8469+
- bearerAuth: []
84348470
responses:
84358471
"200":
84368472
description: Default Response
@@ -8482,7 +8518,7 @@ paths:
84828518
application/json:
84838519
schema:
84848520
schema:
8485-
description: Unauthorized - Authentication required
8521+
description: Unauthorized - Authentication required or invalid token
84868522
type: object
84878523
properties:
84888524
success:
@@ -8501,7 +8537,7 @@ paths:
85018537
application/json:
85028538
schema:
85038539
schema:
8504-
description: Forbidden - Insufficient permissions
8540+
description: Forbidden - Insufficient permissions or scope
85058541
type: object
85068542
properties:
85078543
success:

‎services/backend/src/routes/mcp/categories/list.ts‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { createSchema } from 'zod-openapi';
44
import { McpCategoriesService } from '../../../services/mcpCategoriesService';
55
import { getDb } from '../../../db';
66
import { requirePermission } from '../../../middleware/roleMiddleware';
7+
import { requireAuthenticationAny, requireOAuthScope } from '../../../middleware/oauthMiddleware';
78

89
// Response schema
910
const categorySchema = z.object({
@@ -30,18 +31,46 @@ export default async function listCategories(server: FastifyInstance) {
3031
schema: {
3132
tags: ['MCP Categories'],
3233
summary: 'List all MCP server categories',
33-
description: 'Retrieve all available MCP server categories for organization. No Content-Type header required for this GET request.',
34-
security: [{ cookieAuth: [] }],
34+
description: 'Retrieve all available MCP server categories for organization. Supports both cookie-based authentication (for web users) and OAuth2 Bearer token authentication (for CLI users). Requires mcp:categories:read scope for OAuth2 access. No Content-Type header required for this GET request.',
35+
security: [
36+
{ cookieAuth: [] },
37+
{ bearerAuth: [] }
38+
],
3539
response: {
3640
200: createSchema(listCategoriesResponseSchema),
37-
401: createSchema(errorResponseSchema.describe('Unauthorized - Authentication required')),
38-
403: createSchema(errorResponseSchema.describe('Forbidden - Insufficient permissions')),
41+
401: createSchema(errorResponseSchema.describe('Unauthorized - Authentication required or invalid token')),
42+
403: createSchema(errorResponseSchema.describe('Forbidden - Insufficient permissions or scope')),
3943
500: createSchema(errorResponseSchema)
4044
}
4145
},
42-
preValidation: requirePermission('mcp.categories.view')
46+
preValidation: [
47+
requireAuthenticationAny(),
48+
requireOAuthScope('mcp:categories:read'),
49+
requirePermission('mcp.categories.view')
50+
]
4351
}, async (request, reply) => {
4452
try {
53+
if (!request.user) {
54+
const errorResponse = {
55+
success: false,
56+
error: 'Authentication required'
57+
};
58+
const jsonString = JSON.stringify(errorResponse);
59+
return reply.status(401).type('application/json').send(jsonString);
60+
}
61+
62+
const authType = request.tokenPayload ? 'oauth2' : 'cookie';
63+
const userId = request.user.id;
64+
65+
request.log.debug({
66+
operation: 'list_mcp_categories',
67+
userId,
68+
authType,
69+
clientId: request.tokenPayload?.clientId,
70+
scope: request.tokenPayload?.scope,
71+
endpoint: request.url
72+
}, 'Authentication method determined for MCP categories listing');
73+
4574
const db = getDb();
4675
const categoriesService = new McpCategoriesService(db, server.log);
4776
const categories = await categoriesService.getAllCategories();

0 commit comments

Comments
 (0)