refactor(core,console): use body for PAT operations (#7900)

refactor(core,console): use body for pat operations

fixed #7760

Author: wangsijie

.changeset/mean-impalas-joke.md

@@ -0,0 +1,10 @@
+---
+"@logto/console": patch
+"@logto/core": patch
+---
+
+add body-based personal access token APIs
+
+introduce PATCH/POST endpoints that accept token names in the request body to support special characters while keeping path-based routes for compatibility:
+- PATCH /api/users/{userId}/personal-access-tokens
+- POST /api/users/{userId}/personal-access-tokens/delete

packages/console/src/pages/UserDetails/UserSettings/PersonalAccessTokens/EditTokenModal.tsx

@@ -41,8 +41,8 @@ function EditTokenModal({ userId, token, onClose }: Props) {
   const submit = handleSubmit(
     trySubmitSafe(async (data) => {
       const createdData = await api
-        .patch(`api/users/${userId}/personal-access-tokens/${encodeURIComponent(token.name)}`, {
-          json: data,
+        .patch(`api/users/${userId}/personal-access-tokens`, {
+          json: { currentName: token.name, name: data.name },
         })
         .json<PersonalAccessToken>();
       toast.success(

packages/console/src/pages/UserDetails/UserSettings/PersonalAccessTokens/index.tsx

@@ -69,9 +69,9 @@ function PersonalAccessTokens({ userId }: Props) {
             fieldName="user_details.personal_access_tokens.title_short"
             deleteConfirmation="user_details.personal_access_tokens.delete_confirmation"
             onDelete={async () => {
-              await api.delete(
-                `api/users/${userId}/personal-access-tokens/${encodeURIComponent(token.name)}`
-              );
+              await api.post(`api/users/${userId}/personal-access-tokens/delete`, {
+                json: { name: token.name },
+              });
               void mutate();
             }}
             onEdit={() => {

packages/core/src/queries/personal-access-tokens.ts

@@ -42,10 +42,10 @@ export class PersonalAccessTokensQueries {
     `);
   }
 
-  async deleteByName(appId: string, name: string) {
+  async deleteByName(userId: string, name: string) {
     const { rowCount } = await this.pool.query(sql`
       delete from ${table}
-        where ${fields.userId} = ${appId}
+        where ${fields.userId} = ${userId}
         and ${fields.name} = ${name}
     `);
     if (rowCount < 1) {

packages/core/src/routes/admin-user/personal-access-token.openapi.json

@@ -37,12 +37,38 @@
             "description": "The personal access token name is already in use."
           }
         }
+      },
+      "patch": {
+        "operationId": "UpdatePersonalAccessTokenName",
+        "summary": "Update personal access token",
+        "description": "Update a token for the user by name.",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "currentName": {
+                    "description": "The current name of the token to update."
+                  },
+                  "name": {
+                    "description": "The new token name. Must be unique within the user."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The token was updated successfully."
+          }
+        }
       }
     },
     "/api/users/{userId}/personal-access-tokens/{name}": {
       "delete": {
         "summary": "Delete personal access token",
-        "description": "Delete a token for the user by name.",
+        "description": "Delete a token for the user by name using the legacy path parameter. Deprecated: use the POST /delete endpoint instead to avoid url name encoding issues.",
         "parameters": [
           {
             "name": "name",
@@ -58,12 +84,12 @@
       },
       "patch": {
         "summary": "Update personal access token",
-        "description": "Update a token for the user by name.",
+        "description": "Update a token for the user by name using the legacy path parameter. Deprecated: use the PATCH /personal-access-tokens endpoint instead to avoid url name encoding issues.",
         "parameters": [
           {
             "name": "name",
             "in": "path",
-            "description": "The name of the token."
+            "description": "The current name of the token."
           }
         ],
         "requestBody": {
@@ -72,19 +98,44 @@
               "schema": {
                 "properties": {
                   "name": {
-                    "description": "The token name to update. Must be unique within the user."
+                    "description": "The new token name. Must be unique within the user."
                   }
                 }
               }
             }
           }
         },
         "responses": {
-          "204": {
+          "200": {
             "description": "The token was updated successfully."
           }
         }
       }
+    },
+    "/api/users/{userId}/personal-access-tokens/delete": {
+      "post": {
+        "operationId": "DeletePersonalAccessTokenPost",
+        "summary": "Delete personal access token",
+        "description": "Delete a token for the user by name.",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "properties": {
+                  "name": {
+                    "description": "The name of the token to delete."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "The token was deleted successfully."
+          }
+        }
+      }
     }
   }
 }

packages/core/src/routes/admin-user/personal-access-token.ts

@@ -60,6 +60,10 @@ export default function adminUserPersonalAccessTokenRoutes<T extends ManagementA
     }
   );
 
+  /**
+   * Legacy endpoints that accept the token name via the request path.
+   * Keep them for backward compatibility.
+   */
   router.delete(
     '/users/:userId/personal-access-tokens/:name',
     koaGuard({
@@ -78,6 +82,29 @@ export default function adminUserPersonalAccessTokenRoutes<T extends ManagementA
     }
   );
 
+  // Here we use POST method to avoid potential issues with sending body in DELETE requests.
+  router.post(
+    '/users/:userId/personal-access-tokens/delete',
+    koaGuard({
+      params: z.object({ userId: z.string() }),
+      body: z.object({ name: z.string() }),
+      status: [204, 404],
+    }),
+    async (ctx, next) => {
+      const {
+        params: { userId },
+        body: { name },
+      } = ctx.guard;
+
+      await queries.personalAccessTokens.deleteByName(userId, name);
+      ctx.status = 204;
+
+      return next();
+    }
+  );
+
+  // Legacy endpoint that accepts the token name via the request path.
+  // Keep it for backward compatibility.
   router.patch(
     '/users/:userId/personal-access-tokens/:name',
     koaGuard({
@@ -96,4 +123,34 @@ export default function adminUserPersonalAccessTokenRoutes<T extends ManagementA
       return next();
     }
   );
+
+  router.patch(
+    '/users/:userId/personal-access-tokens',
+    koaGuard({
+      params: z.object({ userId: z.string() }),
+      body: PersonalAccessTokens.updateGuard
+        .pick({ name: true })
+        .required()
+        .extend({ currentName: z.string().optional() }),
+      response: PersonalAccessTokens.guard,
+      status: [200, 400, 404],
+    }),
+    async (ctx, next) => {
+      const {
+        params: { userId },
+        body: { currentName, name },
+      } = ctx.guard;
+
+      /**
+       * `currentName` is optional for backward compatibility with clients that
+       * already send the current name via other channels (for example, in the
+       * request URL). When it is omitted we assume the caller is updating the
+       * token in place without renaming.
+       */
+      const targetName = currentName ?? name;
+
+      ctx.body = await queries.personalAccessTokens.updateName(userId, targetName, name);
+      return next();
+    }
+  );
 }

packages/core/src/routes/swagger/utils/operation-id.ts

@@ -70,6 +70,8 @@ export const customRoutes: Readonly<RouteDictionary> = Object.freeze({
   // Users
   'post /users/:userId/roles': 'AssignUserRoles',
   'post /users/:userId/password/verify': 'VerifyUserPassword',
+  'post /users/:userId/personal-access-tokens/delete': 'DeletePersonalAccessTokenByName',
+  'patch /users/:userId/personal-access-tokens': 'UpdatePersonalAccessTokenByName',
   // Dashboard
   'get /dashboard/users/total': 'GetTotalUserCount',
   'get /dashboard/users/new': 'GetNewUserCounts',

packages/integration-tests/src/api/admin-user.ts

@@ -155,12 +155,26 @@ export const getUserPersonalAccessTokens = async (userId: string) =>
   authedAdminApi.get(`users/${userId}/personal-access-tokens`).json<PersonalAccessToken[]>();
 
 export const deletePersonalAccessToken = async (userId: string, name: string) =>
-  authedAdminApi.delete(`users/${userId}/personal-access-tokens/${name}`);
+  authedAdminApi.post(`users/${userId}/personal-access-tokens/delete`, { json: { name } });
 
 export const updatePersonalAccessToken = async (
   userId: string,
   name: string,
   body: Record<string, unknown>
+) =>
+  authedAdminApi
+    .patch(`users/${userId}/personal-access-tokens`, {
+      json: { ...body, currentName: name },
+    })
+    .json<PersonalAccessToken>();
+
+export const deletePersonalAccessTokenLegacy = async (userId: string, name: string) =>
+  authedAdminApi.delete(`users/${userId}/personal-access-tokens/${name}`);
+
+export const updatePersonalAccessTokenLegacy = async (
+  userId: string,
+  name: string,
+  body: Record<string, unknown>
 ) =>
   authedAdminApi
     .patch(`users/${userId}/personal-access-tokens/${name}`, {

packages/integration-tests/src/tests/api/admin-user.personal-access-tokens.test.ts

@@ -3,9 +3,11 @@ import { HTTPError } from 'ky';
 import {
   createPersonalAccessToken,
   deletePersonalAccessToken,
+  deletePersonalAccessTokenLegacy,
   deleteUser,
   getUserPersonalAccessTokens,
   updatePersonalAccessToken,
+  updatePersonalAccessTokenLegacy,
 } from '#src/api/admin-user.js';
 import { createUserByAdmin } from '#src/helpers/index.js';
 import { randomString } from '#src/utils.js';
@@ -112,4 +114,39 @@ describe('personal access tokens', () => {
 
     await deleteUser(user.id);
   });
+
+  it('should handle special characters in token name with body-based endpoints', async () => {
+    const user = await createUserByAdmin();
+    const nameWithSpecialChars = `token-with-special-chars-${randomString()}!@#$%`;
+    const pat = await createPersonalAccessToken({
+      userId: user.id,
+      name: nameWithSpecialChars,
+    });
+
+    expect(pat.name).toBe(nameWithSpecialChars);
+
+    const newName = `updated-${randomString()}`;
+    const updatedPat = await updatePersonalAccessToken(user.id, pat.name, { name: newName });
+    expect(updatedPat.name).toBe(newName);
+
+    await deletePersonalAccessToken(user.id, updatedPat.name);
+    expect(await getUserPersonalAccessTokens(user.id)).toEqual([]);
+
+    await deleteUser(user.id);
+  });
+
+  it('should support legacy path-based endpoints', async () => {
+    const user = await createUserByAdmin();
+    const name = randomString();
+    await createPersonalAccessToken({ userId: user.id, name });
+
+    const newName = randomString();
+    const updated = await updatePersonalAccessTokenLegacy(user.id, name, { name: newName });
+    expect(updated.name).toBe(newName);
+
+    await deletePersonalAccessTokenLegacy(user.id, newName);
+    expect(await getUserPersonalAccessTokens(user.id)).toEqual([]);
+
+    await deleteUser(user.id);
+  });
 });