Define account grant token admin APIs by nighca · Pull Request #3284 · goplus/builder

nighca · 2026-06-17T04:04:11Z

Summary

Add admin APIs for listing account user app grants and retrieving grant details.
Add admin APIs for listing, creating, and revoking tokens under a user app grant.
Add OpenAPI schemas for account app grants, account app token metadata, and one-time token creation responses.

Notes

This PR only defines the API contract. Backend and Admin UI implementation will follow separately.

The token creation API intentionally stays generic under grant tokens. Currently it creates access tokens only, with explicit expiration, no refresh token, and a one-time returned token value.

Checks

Parsed docs/openapi.yaml as YAML
git diff --check

gemini-code-assist

Code Review

This pull request updates the OpenAPI specification to add new admin endpoints for managing account user app grants and their associated OAuth tokens, including listing, retrieving, creating, and deleting tokens. Feedback on the changes highlights that tokenFamilyID is incorrectly marked as required in the AccountAppToken schema, which may cause validation failures for access tokens that do not participate in refresh token rotation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

nighca · 2026-06-17T09:27:41Z

+        scope:
+          description: Account OAuth scope associated with the token.
+          $ref: "#/components/schemas/OAuthScope"
+        remark:


给原来的 model token 额外增加了 remark 字段

我搜了下这种场景大部分好像都是 name+description 的组合，比较少见叫 remark/note 这种

我们现在 AccountAppSecret 里其实有个 name，所以感觉这里也可以统一一下叫 name

可以的，那就叫 name 吧

done f8c861d

aofei · 2026-06-23T07:06:14Z

+            - refreshToken
+          examples:
+            - accessToken
+        tokenFamilyID:


这里暴露 tokenFamilyID 的目的是什么？

这次展示的 token 列表不只是这种 admin 创建、长期有效的 token，也包括正常登录操作产生的 token 对

对于后者，tokenFamilyID 代表的联系是有意义的，比如现在可以通过人肉阅读 tokenFamilyID 来把 refresh token 和 access token 对应上，后面我们也可能会在 UI 上提供对于指定的 token 查看其“关联 token(s)”的能力

我不是很倾向于暴露tokenFamilyID 主要是因为这个概念太内部了，如果要提供表达关联关系的能力，那直接引入一个新的 api 感觉会更好一点，而且 api 上也不一定非得用 family 这个说法

admin 接口的用户一定程度上是“内部的人”，接口跟 model 上的概念保持一致对 admin 用户与开发者的心智模型或描述方式保持一致是有好处的

如果要提供表达关联关系的能力，那直接引入一个新的 api 感觉会更好一点，而且 api 上也不一定非得用 family 这个说法

那其实是在舍弃“family”去定义一个新的业务概念了，毕竟这种关系总是需要被明确描述的。

我先把这个字段在接口上干掉吧，可以之后在提供更为完善的 token 管理能力时再去考虑这个问题

嗯那先暂时干掉好了，等我们之后需要展示关联关系的时候再看

f8c861d done

aofei · 2026-06-23T07:10:49Z

+
+  /admin/account/users/{userID}/grants/{grantID}/tokens/{tokenID}:
+    delete:
+      operationId: revokeAdminAccountUserGrantToken


这里 operationId 要不也用 deleteXXX 好了，主要我们别的地方也是这个风格，比如 deleteAdminAccountSession，其他文案上可以用 revoke

done f8c861d

aofei · 2026-06-23T07:16:18Z

+        - Account Admin
+      summary: List account user app grants as admin
+      description: |
+        Retrieve a list of active app grants of an account user.


这个会列出所有 token 吗？包括普通登录流程产生的那种段生命周期的

会的，目前没有（也没打算提供）可靠的方式来区分这两类 token

aofei · 2026-06-23T07:18:54Z

+        "404":
+          description: Account user not found.
+
+  /admin/account/users/{userID}/grants/{grantID}:


这个 endpoint 是不是应该加个 DELETE 版本

这次没用到这个能力，所以先没加 🤣

好吧那可以先不要

aofei · 2026-06-23T07:54:28Z

+        scope:
+          description: Account OAuth scope associated with the token.
+          $ref: "#/components/schemas/OAuthScope"
+        remark:


我搜了下这种场景大部分好像都是 name+description 的组合，比较少见叫 remark/note 这种

我们现在 AccountAppSecret 里其实有个 name，所以感觉这里也可以统一一下叫 name

aofei · 2026-06-23T07:59:24Z

+        "404":
+          description: Account user not found.
+
+  /admin/account/users/{userID}/grants/{grantID}:


除了 /admin/account/users/{userID}/grants 其他应该都不需要搞成 user 的子资源，比如这里用 /admin/account/grants/{grantID} 会更符合我们的风格

可以的，我们现在 API 上是鼓励定义为 top-level resource 是吧？

现在原则上如果一个资源有自己的全局 id，并且后续操作不需要依赖 parent path 来消歧义，就适合暴露成 top-level

那 token 的操作也以 top-level resource 的方式来定义？如果考虑跟 oauth token 区分开的话（这俩是相关但不完全相同的概念），也叫 app-token？

如果考虑跟 oauth token 区分开的话（这俩是相关但不完全相同的概念），也叫 app-token？

如果搞出来 app-grants/*/app-tokens 又有点怪怪的，感觉 top-level 的时候叫完整的名字（app-grant/app-token），作为子 resource 的时候用不完整的名字（grant/token）好些？比如

users/<uid>/grants: app grants for user uid

app-grants/<gid>/tokens: app tokens for app grant gid

app-tokens/<tid>: app token tid

app grant 本身就是 user-app 授权关系，所以适合 top-level，token 是 app grant 下的一次签发结果，语义上离不开 grant

这个可以类比 project release，project 是主要业务资源，所以有 /projects/{projectID}，但 release 语义上离不开 project，所以是 /projects/{projectID}/releases/{releaseID}，而不是 /releases/{releaseID}

这么理解也说得通，可以按这个设定来；我来调整下，类似这样：

users/<uid>/app-grants

app-grants/<gid>/tokens

app-grants/<gid>/tokens/<tid>

done f8c861d

aofei · 2026-06-23T08:02:54Z

+        "404":
+          description: Account user or app grant not found.
+
+  /admin/account/users/{userID}/grants/{grantID}/tokens:


path 里统一用 app grant 会好一点，比如这里写成 /admin/account/app-grants/{appGrantID}/tokens

主要是单独 grant 感觉有点宽泛，oauth 已经有了个 grant

done f8c861d

aofei · 2026-06-24T03:22:51Z

+        name:
+          description: Human-readable token name.
+          type: string
+          minLength: 1


这个可以不要，并且也不能是 required，因为像是登录流程自动创建的那些 token 是没有 name 的

另外 name 字段要不放在 tokenType 前面好了，看起来会顺一点

啊是的，不应该加这个 minLength

并且也不能是 required，因为像是登录流程自动创建的那些 token 是没有 name 的

这种我打算让它们都更新为空字符串的，不在接口上体现 optional

另外 name 字段要不放在 tokenType 前面好了，看起来会顺一点

可以的

这种我打算让它们都更新为空字符串的，不在接口上体现 optional

这样也可以

done d749643

CreateAccountAppTokenRequest 中 name 的 minLength 留着了，目前走这个接口创建 token 要求指定 name

Define account grant token admin APIs

682cf3f

gemini-code-assist Bot reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/openapi.yaml

vercel Bot deployed to Preview – builder June 17, 2026 04:06 View deployment

Refine account grant token API spec

1f01e57

vercel Bot deployed to Preview – builder June 17, 2026 09:22 View deployment

Address account token API review comments

7ae2b4c

vercel Bot deployed to Preview – builder June 17, 2026 09:26 View deployment

Clarify admin-created token scope

adc0a87

vercel Bot deployed to Preview – builder June 17, 2026 09:29 View deployment

Refine account token remark description

dfdfbfb

nighca commented Jun 17, 2026

View reviewed changes

nighca marked this pull request as ready for review June 17, 2026 09:31

vercel Bot deployed to Preview – builder June 17, 2026 09:32 View deployment

This comment was marked as resolved.

Sign in to view

Address account token API review

c79396d

vercel Bot deployed to Preview – builder June 17, 2026 09:55 View deployment

Clarify account grant list returns active grants

f4693ad

vercel Bot deployed to Preview – builder June 17, 2026 10:02 View deployment

aofei reviewed Jun 23, 2026

View reviewed changes

Update account grant token API spec

f8c861d

vercel Bot deployed to Preview – builder June 24, 2026 01:59 View deployment

aofei reviewed Jun 24, 2026

View reviewed changes

Remove minLength constraint from token name in API spec

d749643

nighca force-pushed the issue-3275 branch from 5dbe4a6 to d749643 Compare June 24, 2026 03:45

vercel Bot deployed to Preview – builder June 24, 2026 03:47 View deployment

aofei approved these changes Jun 24, 2026

View reviewed changes

aofei merged commit cdc82cd into goplus:dev Jun 24, 2026
5 checks passed

Uh oh!

Conversation

nighca commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes

Checks

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

nighca commented Jun 17, 2026 •

edited

Loading