roblox-oauth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

roblox-oauth

When to Use

使用场景

Use this skill when the task is mainly about Roblox OAuth 2.0 delegated authorization for Open Cloud:

Registering or configuring an OAuth app in Creator Dashboard.
Choosing between confidential and public client implementations.
Building the authorization code flow, especially with PKCE.
Constructing authorization URLs and handling redirect callbacks.
Exchanging authorization codes, refreshing tokens, introspecting tokens, or revoking sessions.
Picking the minimum OAuth scopes for a user-authorized integration.
Validating which resources a token can access after user consent.
Setting up localhost or sample-app-style development for OAuth testing.
Debugging OAuth-specific errors, redirect mismatches, token misuse, or scope failures.

Do not use this skill when the task is mainly about:

General Open Cloud request construction, API keys, webhooks, or non-OAuth cloud automation.
In-experience scripting architecture, remotes, replication, or gameplay code.
DataStore or MemoryStore design.

当任务主要围绕Roblox OAuth 2.0委托授权用于Open Cloud时，使用本技能：

在Creator Dashboard中注册或配置OAuth应用。
选择机密客户端与公开客户端实现方案。
构建授权码流程，尤其是带PKCE的流程。
构造授权URL并处理重定向回调。
交换授权码、刷新令牌、校验令牌或撤销会话。
为用户授权的集成选择最小的OAuth权限范围。
在用户授权后验证令牌可访问的资源。
搭建localhost或示例应用风格的开发环境以测试OAuth。
调试OAuth相关错误，如重定向不匹配、令牌滥用或权限范围失败。

当任务主要涉及以下内容时，请勿使用本技能：

通用Open Cloud请求构造、API密钥、Webhook或非OAuth云自动化。
游戏内脚本架构、远程调用、复制或游戏玩法代码。
DataStore或MemoryStore设计。

Decision Rules

决策规则

Use this skill if the integration needs user-granted or creator-granted delegated access rather than server-owned API keys.
Prefer authorization code flow with PKCE for all clients and require PKCE for public clients.
Treat browser and mobile apps as public clients that cannot safely hold a client secret.
Treat apps with a secure backend as confidential clients and keep the client secret server-side only.
Request the minimum scopes needed for the app's actual function.
Add
```
openid
```
when the app needs an ID token, and add
```
profile
```
only when it truly needs profile claims.
If the task shifts to endpoint selection, request shaping, rate limits, or webhooks rather than OAuth mechanics, hand off to
```
roblox-cloud
```
.
If the task shifts to in-experience runtime architecture or persistence design, hand off to the appropriate Roblox skill.
If a request mixes OAuth with out-of-scope architecture, answer only the OAuth portion and explicitly exclude the rest.

如果集成需要用户或创作者授予的委托访问权限，而非服务器自有API密钥，则使用本技能。
为所有客户端优先选择带PKCE的授权码流程，且公开客户端必须使用PKCE。
将浏览器和移动应用视为无法安全保存客户端密钥的公开客户端。
将拥有安全后端的应用视为机密客户端，且仅在服务器端保存客户端密钥。
请求应用实际功能所需的最小权限范围。
当应用需要ID令牌时添加
```
openid
```
，仅在确实需要身份声明时添加
```
profile
```
。
如果任务转向端点选择、请求构造、速率限制或Webhook而非OAuth机制，则移交至
```
roblox-cloud
```
处理。
如果任务转向游戏内运行时架构或持久化设计，则移交至对应的Roblox技能处理。
如果请求混合了OAuth与超出范围的架构内容，仅回答OAuth部分并明确排除其他内容。

Instructions

操作指南

Confirm the OAuth use case:
- User- or creator-delegated access to Open Cloud resources.
- App type: confidential or public.
- Whether identity is needed in addition to API access.
Register or review the app configuration:
- Ensure the developer is ID verified if they need to register and publish apps.
- Record the client ID.
- Store the client secret immediately and securely if the app is confidential, because Roblox only shows it once.
- Add only the necessary scopes.
- Add exact redirect URLs for production and local development.
Design the flow before coding:
- Use authorization code flow.
- Use PKCE for all clients; it is mandatory for public clients.
- Generate a fresh high-entropy
```
state
```
  per authorization attempt.
- Generate a fresh
```
code_verifier
```
  and
```
code_challenge
```
  per authorization attempt.
- Use
```
nonce
```
  when OIDC identity binding is relevant.
Build the authorization request correctly:
- Send users to
```
https://apis.roblox.com/oauth/v1/authorize
```
  .
- Include
```
client_id
```
  ,
```
redirect_uri
```
  ,
```
scope
```
  , and
```
response_type=code
```
  .
- Include
```
code_challenge
```
  and
```
code_challenge_method=S256
```
  for PKCE.
- Do not expose a confidential client secret in browser or mobile code.
Handle the callback defensively:
- Verify the returned
```
state
```
  before using the
```
code
```
  .
- Handle both success (
```
code
```
  ) and failure (
```
error
```
  ,
```
error_description
```
  ) query parameters.
- Treat the authorization code as short-lived and single-use.
Exchange the code for tokens at
```
POST /oauth/v1/token
```
:
- Use
```
application/x-www-form-urlencoded
```
  .
- Send the code, client ID, grant type, and either
```
code_verifier
```
  or confidential-client credentials.
- Store refresh tokens only on trusted server-side systems.
Manage token lifecycle explicitly:
- Access tokens last about 15 minutes.
- Refresh tokens last about 90 days and are single-use for refresh.
- Replace the stored refresh token atomically after every successful refresh response.
- Revoke sessions with
```
POST /oauth/v1/token/revoke
```
  when disconnecting an app.
Validate what the token can actually do:
- Use
```
GET /oauth/v1/userinfo
```
  for identity claims.
- Use
```
POST /oauth/v1/token/resources
```
  when the app must confirm resource-level access granted by the user.
- Use
```
POST /oauth/v1/token/introspect
```
  only for token activity and claims; it is not a substitute for resource authorization checks.
Keep scope and risk tight:
- Match scopes to actual endpoints and resource ownership needs.
- Treat medium, high, and critical endpoint categories as a least-privilege warning signal during design and review.
- Avoid expanding the skill into general Open Cloud endpoint implementation.
Keep the response inside scope:

Focus on app registration, auth flow design, tokens, scopes, local development, and OAuth-specific errors.
Do not drift into API-key-first cloud integrations, gameplay architecture, or data-service design.

确认OAuth使用场景：
- 用户或创作者委托访问Open Cloud资源。
- 应用类型：机密或公开。
- 除API访问外是否需要身份信息。
注册或审核应用配置：
- 如果开发者需要注册并发布应用，确保其已完成身份验证。
- 记录客户端ID。
- 如果是机密客户端，立即安全存储客户端密钥，因为Roblox仅显示一次密钥。
- 仅添加必要的权限范围。
- 为生产环境和本地开发添加精确的重定向URL。
编码前设计流程：
- 使用授权码流程。
- 为所有客户端使用PKCE；公开客户端必须使用。
- 每次授权尝试生成新的高熵
```
state
```
  。
- 每次授权尝试生成新的
```
code_verifier
```
  和
```
code_challenge
```
  。
- 当OIDC身份绑定相关时使用
```
nonce
```
  。
正确构建授权请求：
- 将用户导向
```
https://apis.roblox.com/oauth/v1/authorize
```
  。
- 包含
```
client_id
```
  、
```
redirect_uri
```
  、
```
scope
```
  和
```
response_type=code
```
  。
- 为PKCE包含
```
code_challenge
```
  和
```
code_challenge_method=S256
```
  。
- 不要在浏览器或移动代码中暴露机密客户端密钥。
防御性处理回调：
- 在使用
```
code
```
  前验证返回的
```
state
```
  。
- 处理成功（
```
code
```
  ）和失败（
```
error
```
  、
```
error_description
```
  ）查询参数。
- 授权码是短期且一次性的。
在
```
POST /oauth/v1/token
```
交换代码获取令牌：
- 使用
```
application/x-www-form-urlencoded
```
  格式。
- 发送代码、客户端ID、授权类型，以及
```
code_verifier
```
  或机密客户端凭据。
- 仅在可信服务器端系统存储刷新令牌。
显式管理令牌生命周期：
- 访问令牌有效期约15分钟。
- 刷新令牌有效期约90天，且刷新时只能使用一次。
- 每次成功刷新后，原子性替换存储的刷新令牌。
- 断开应用连接时，使用
```
POST /oauth/v1/token/revoke
```
  撤销会话。
验证令牌实际可执行操作：
- 使用
```
GET /oauth/v1/userinfo
```
  获取身份声明。
- 当应用必须确认用户授予的资源级访问权限时，使用
```
POST /oauth/v1/token/resources
```
  。
- 仅将
```
POST /oauth/v1/token/introspect
```
  用于令牌活动和声明查询；它不能替代资源授权检查。
严格控制权限范围与风险：
- 权限范围需匹配实际端点和资源所有权需求。
- 在设计和审核过程中，将中等、高和关键端点类别视为最小权限警告信号。
- 避免将技能扩展到通用Open Cloud端点实现。
保持响应在范围内：
- 专注于应用注册、认证流程设计、令牌、权限范围、本地开发和OAuth相关错误。
- 不要偏离到基于API密钥的云集成、游戏玩法架构或数据服务设计。

Using References

参考资料使用

Open
```
references/oauth-overview.md
```
first for roles, grant type choice, and OIDC basics.
Open
```
references/oauth-registration.md
```
when the task is about Creator Dashboard setup, redirect URL rules, private mode limits, or app review.
Open
```
references/oauth-development-guide.md
```
when implementing PKCE, the authorization URL, callback handling, or token storage.
Open
```
references/oauth-reference.md
```
for exact OAuth endpoints, token lifetimes, token validation helpers, and discovery metadata.
Open
```
references/oauth-sample-app.md
```
for localhost setup, environment-variable patterns, and how the sample app wires the flow together.
Open
```
references/scopes-reference.md
```
when mapping app behavior to the minimum required scopes.
Open
```
references/risk-level-reference.md
```
when you need to reason about endpoint sensitivity before requesting powerful scopes.
Open
```
references/cloud-auth-related-error-guidance.md
```
when triaging OAuth and token-related failures against Open Cloud error patterns.

首先打开
```
references/oauth-overview.md
```
了解角色、授权类型选择和OIDC基础知识。
当任务涉及Creator Dashboard设置、重定向URL规则、私有模式限制或应用审核时，打开
```
references/oauth-registration.md
```
。
当实现PKCE、授权URL、回调处理或令牌存储时，打开
```
references/oauth-development-guide.md
```
。
打开
```
references/oauth-reference.md
```
获取精确的OAuth端点、令牌有效期、令牌验证工具和发现元数据。
打开
```
references/oauth-sample-app.md
```
了解localhost设置、环境变量模式以及示例应用如何串联流程。
当映射应用行为到所需最小权限范围时，打开
```
references/scopes-reference.md
```
。
在请求高权限范围前需要评估端点敏感度时，打开
```
references/risk-level-reference.md
```
。
排查OAuth和令牌相关故障并匹配Open Cloud错误模式时，打开
```
references/cloud-auth-related-error-guidance.md
```
。

Checklist

检查清单

The task actually requires delegated OAuth access, not API-key-based automation.
The client is classified correctly as confidential or public.
PKCE is included, or the design is rejected if a public client tries to skip it.
Redirect URLs are exact matches and valid for the intended environment.
Requested scopes are minimal and match the integration's real behavior.
```
openid
```
is included only when identity data or an ID token is needed.
```
state
```
is generated, stored, and verified on callback.
The authorization code is exchanged promptly and only once.
Access and refresh token storage stays off untrusted clients.
Refresh token rotation is handled by replacing the stored refresh token after refresh.
The app uses
```
userinfo
```
,
```
introspect
```
, and
```
token/resources
```
for their distinct purposes.
The guidance stays out of general Open Cloud request mechanics, gameplay scripting, and data architecture.

任务确实需要委托OAuth访问，而非基于API密钥的自动化。
客户端被正确分类为机密或公开类型。
已包含PKCE，若公开客户端尝试跳过则拒绝该设计。
重定向URL与目标环境完全匹配且有效。
请求的权限范围最小且与集成的实际行为匹配。
仅在需要身份数据或ID令牌时包含
```
openid
```
。
已生成、存储并在回调时验证
```
state
```
。
授权码已及时交换且仅使用一次。
访问令牌和刷新令牌未存储在不可信客户端。
刷新令牌轮换通过刷新后替换存储的刷新令牌实现。
应用根据不同用途使用
```
userinfo
```
、
```
introspect
```
和
```
token/resources
```
。
指导内容未涉及通用Open Cloud请求机制、游戏脚本编写和数据架构。

Common Mistakes

常见错误

Using API keys and OAuth interchangeably instead of choosing the auth model first.
Shipping a confidential client secret in frontend or mobile code.
Skipping PKCE, especially for public clients.
Forgetting to verify
```
state
```
on the callback.
Assuming a refresh token can be reused multiple times after a successful refresh.
Forgetting that authorization codes expire quickly and are single-use.
Requesting
```
profile
```
without
```
openid
```
.
Requesting broad scopes during development instead of the minimum required set.
Assuming token introspection proves resource ownership or consented resource coverage.
Adding or changing scopes without reauthorizing users.
Treating non-OAuth Open Cloud issues as part of this skill instead of handing them to
```
roblox-cloud
```
.

交替使用API密钥和OAuth，而非先选择认证模型。
在前端或移动代码中包含机密客户端密钥。
跳过PKCE，尤其是公开客户端。
忘记在回调时验证
```
state
```
。
假设刷新令牌在成功刷新后可多次使用。
忘记授权码有效期短且仅可使用一次。
未添加
```
openid
```
就请求
```
profile
```
。
开发期间请求宽泛的权限范围而非所需的最小集合。
假设令牌校验可证明资源所有权或用户同意的资源覆盖范围。
未重新授权用户就添加或修改权限范围。
将非OAuth的Open Cloud问题视为本技能范畴，而非移交至
```
roblox-cloud
```
处理。

Examples

示例

Public web or mobile app

公开网页或移动应用

Use authorization code flow with PKCE.
Keep all secrets off the client.
Verify
```
state
```
, exchange the code on a trusted backend when possible, and store refresh tokens securely.

使用带PKCE的授权码流程。
不在客户端存储任何密钥。
验证
```
state
```
，尽可能在可信后端交换代码，并安全存储刷新令牌。

Confidential server app

机密服务器应用

Register the app, store the secret once, and still use PKCE.
Use the server to exchange codes, refresh tokens, and call Open Cloud with bearer tokens.

注册应用，一次性存储密钥，且仍使用PKCE。
使用服务器交换代码、刷新令牌，并使用Bearer令牌调用Open Cloud。

Local development

本地开发

Add
```
http://localhost:<port>/oauth/callback
```
as a redirect URL.
Store client ID and secret in environment variables.
Test the full login, callback, token exchange, refresh, and logout or revoke path before requesting more scopes or review.

添加
```
http://localhost:<port>/oauth/callback
```
作为重定向URL。
在环境变量中存储客户端ID和密钥。
在请求更多权限范围或审核前，测试完整的登录、回调、令牌交换、刷新以及注销或撤销路径。