OAuth 2.0 身份验证是一个可能会在未来版本中发生变化的 beta 特性。所有开放云端点也支持 API 密钥身份验证。
有关 OAuth 2.0 的完整实施指南和信息，包括示例应用，请参见 OAuth 2.0 概述。
本文档描述了用于实现 OAuth 2.0 授权代码流程的端点，以及在您的应用中实现身份验证时有用的其他端点。
基础 URL
端点
授权
GET v1/authorize
从用户那里获取授权以使用他们的 Roblox 账户进行身份验证。 期望一个有效的授权 URL，该 URL 由指定参数构建。该端点支持 PKCE 授权。
查询参数
| 名称 | 描述 | 必需 | 示例 |
|---|---|---|---|
| client_id | 应用程序的客户端 ID。 | 是 | 816547628409595165403873012 |
| redirect_uri | 用户在完成授权流程后被重定向回的 URL。 | 是 | `https://www.roblox.com/example-redirect`` |
| scope | 请求的范围，以空格分隔。使用 openid 范围来接收 ID 令牌。使用 openid 和 profile 范围来获取更多用户信息。 | 是 | openid profile |
| response_type | 应用程序希望返回的凭证。默认值是授权代码授权类型。 | 是 | none, code |
| prompt | 指定向用户显示哪些身份验证和同意页面。某些屏幕对于第三方应用是必需的，无法跳过。 | 否 | none, login, consent, select_account |
| nonce | 将令牌与客户端绑定的加密数字。 | 否 | <random_value_1> |
| state | 防止跨站请求伪造的一个不透明值，这是一种恶意攻击。在授权后传回应用程序。 | 否 | <app-provided-opaque-value> |
| code_challenge | 将 code_challenge_method 应用于 code_verifier 的结果字符串。 | 否 | Base64-URL 编码字符串 |
| code_challenge_method | 应用于 code_verifier 的函数。 | 否 | S256 |
请求
指向授权流程的示例请求
响应
在调用此端点后，用户将被重定向到指定的重定向 URL，并在 code 查询参数中带上授权代码。 授权代码：
- 有效期为一分钟。
- 只能使用一次。
- 使用后无效。
令牌交换
要获取 API 访问令牌，请用 授权代码 交换一组机密令牌。所有令牌端点支持两种类型的客户端身份验证：
- 使用授权头的 HTTP 基本身份验证方案： Authorization: Basic Base64 编码(<client_id>:<client_secret>)。
- 在请求体中作为参数提供客户端 ID 和密钥。
以下列表描述了您从此端点接收到的各种令牌。
访问令牌 - 表示创作者或用户授权第三方应用访问其受保护的 Roblox 资源。它是一个表示特定范围、生命周期和其他访问属性的字符串。一旦 Roblox 授权服务器向应用程序发放访问令牌，该令牌：
- 有效期为 15 分钟。
- 在过期之前可以多次使用。
- 如果应用用户撤销了授权，则可以在过期之前使其失效。
刷新令牌 - 刷新授权会话。应用程序可以使用刷新令牌获取一组新的令牌，包括访问令牌、刷新令牌和 ID 令牌。刷新令牌：
- 有效期为 90 天。
- 在过期之前只能使用一次来刷新令牌。
- 如果应用用户撤销了授权，则可以在过期之前使其失效。
ID 令牌 - 提供用户身份已被验证的证明。其内容取决于请求的范围，可以包含基本用户信息，包括用户的 Roblox 显示名称和用户名。ID 令牌仅用于身份验证目的，并不提供访问任何 Roblox 资源的权限。
POST v1/token
使用授权代码获取一组令牌。
请求
(x-www-form-urlencoded)
| 键 | 值 |
|---|---|
| code | <authorization code> |
| code_verifier | <pkce code verifier value> |
| grant_type | authorization_code |
| client_id | <client_id> |
| client_secret | <client_secret> |
示例获取令牌请求
响应
示例获取令牌响应
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 899,
"scope": "universe-messaging-service:publish"
}
POST v1/token
使用刷新令牌获取一组令牌。
请求
(x-www-form-urlencoded)
| 键 | 值 |
|---|---|
| grant_type | refresh_token |
| refresh_token | <refresh_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
示例刷新令牌请求
响应
示例刷新令牌响应
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 899,
"scope": "universe-messaging-service:publish"
}
POST v1/token/introspect
接收有关令牌的信息。验证令牌是否当前有效且尚未过期。对于无状态验证很有用。仅在您访问的 API 不需要资源时使用，例如资产 API，或者如果您只想查看令牌的特定声明。
即使用户已撤销与访问令牌相关的授权，该端点仍会将访问令牌显示为 valid: true，因为它根据其生命周期（通常为访问令牌的 15 分钟）检查令牌是否处于活动状态。
请求
(x-www-form-urlencoded)
| 键 | 值 |
|---|---|
| token | <access_token>，<refresh_token> 或 <id_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
示例检查令牌请求
响应
示例检查令牌响应
{
"active": true,
"jti": "RT.2GcjvTduKzk6QY9tjTfm",
"iss": "https://apis.roblox.com/oauth/",
"token_type": "Bearer",
"client_id": "840974200211308101",
"aud": "4239311013248676173",
"sub": "1516563360",
"scope": "universe-messaging-service:publish",
"exp": 1676394509,
"iat": 1660842510
}
POST v1/token/resources
检查令牌是否可以通过获取用户给予权限的用户资源列表来访问特定资源。这对于有状态验证很有用。
请求
(x-www-form-urlencoded)
| 键 | 值 |
|---|---|
| token | <access_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
示例获取令牌资源请求
响应
值 U 在 ids 中指示某个范围已授予对授权 owner 拥有的资源的访问权限。
示例获取令牌资源响应
{
"resource_infos": [
{
"owner": {
"id": "1516563360",
"type": "User"
},
"resources": {
"universe": {
"ids": ["3828411582"]
},
"creator": {
"ids": ["U"]
}
}
}
]
}
POST v1/token/revoke
使用提供的刷新令牌撤销授权会话。
请求
(x-www-form-urlencoded)
| 键 | 值 |
|---|---|
| token | <refresh_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
示例撤销令牌请求
响应
200 OK，无响应内容
用户信息
GET /v1/userinfo
获取 Roblox 用户 ID 和其他用户元数据。
请求
授权头: Authorization: Bearer <access_token>
示例获取用户信息请求
响应
您可以使用 sub 值来唯一标识用户。用户可以更改其 Roblox 用户名和显示名称，因此请不要将它们用作唯一标识符来引用您应用中的用户。
| 声明 | 描述 |
|---|---|
| sub | Roblox 用户 ID。 |
| name | Roblox 显示名称。 |
| nickname | Roblox 显示名称。 |
| preferred_username | Roblox 用户名。 |
| created_at | Roblox 账户创建时间，按 Unix 时间戳表示。 |
| profile | Roblox 账户个人资料 URL。 |
| picture | Roblox 头像图像。如果头像图像尚未生成或已被审核，则可以为空。 |
示例用户（带个人资料范围）
{
"sub": "1516563360",
"name": "exampleuser",
"nickname": "exampleuser",
"preferred_username": "exampleuser",
"created_at": 1584682495,
"profile": "https://www.roblox.com/users/1516563360/profile",
"picture": "https://tr.rbxcdn.com/03dc2a9abe7b1aacaaf93ea46d5c0646/150/150/AvatarHeadshot/Png"
}
示例用户（无个人资料范围）
{
"sub": "1516563360"
}
发现
OpenID 连接 (OIDC) 发现文档是一个 JSON 文档，包含有关开放云配置详细信息的元数据，包括支持的与身份相关的范围和声明列表。您可以使用它动态发现有关开放云 OAuth 2.0 端点和配置的信息，例如授权端点、令牌端点和公钥集。
在从发现文档 URI 检索并获取发现文档后，您可以手动检查响应中的字段以验证信息，或创建自己的自定义库映射响应模式中的字段来自动化您的工作流程。
GET .well-known/openid-configuration
响应
所有发现文档响应遵循与以下示例响应相同的模式。
并非所有以下范围和声明都可供第三方应用程序创建者使用，因为某些范围只能由官方 Roblox 应用程序使用。
示例发现文档响应
{
"issuer": "https://apis.roblox.com/oauth/",
"authorization_endpoint": "https://apis.roblox.com/oauth/v1/authorize",
"token_endpoint": "https://apis.roblox.com/oauth/v1/token",
"introspection_endpoint": "https://apis.roblox.com/oauth/v1/token/introspect",
"revocation_endpoint": "https://apis.roblox.com/oauth/v1/token/revoke",
"resources_endpoint": "https://apis.roblox.com/oauth/v1/token/resources",
"userinfo_endpoint": "https://apis.roblox.com/oauth/v1/userinfo",
"jwks_uri": "https://apis.roblox.com/oauth/v1/certs",
"registration_endpoint": "https://create.roblox.com/dashboard/credentials",
"service_documentation": "https://create.roblox.com/docs/reference/cloud",
"scopes_supported": [
"openid",
"profile",
"email",
"verification",
"credentials",
"age",
"premium",
"roles"
],
"response_types_supported": ["none", "code"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["ES256"],
"claims_supported": [
"sub",
"type",
"iss",
"aud",
"exp",
"iat",
"nonce",
"name",
"nickname",
"preferred_username",
"created_at",
"profile",
"email",
"email_verified",
"verified",
"age_bracket",
"premium",
"roles",
"internal_user"
],
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic"
]
}