OAuth 2.0 身份验证是一个可能在未来版本中更改的测试功能。所有开放云端端点也支持API密钥验证。
了解 OAuth 2.0 的完整实施指南和信息，包括示例应用程App，请参阅 OAuth 2.0 概览。
本文描述了您调用以实现 OAuth 2.0 授权代码流的端点，以及其他有用于在应用程序中实现身份验证的端点。
Base URL
Endpoints
授权
GET v1/authorize
获得用户的授权以使用他们的 Roblox 帐户进行身份验证。期望使用指定参数构建的有效授权 URL。此端点支持 PKCE 授权。
查询参数
| 名称 | 描述 | 需要 | 示例 |
|---|---|---|---|
| client_id | 应用的客户 ID。 | yes | 816547628409595165403873012 |
| redirect_uri | 用户在完成授权流程后返回的 URL。 | 是 | https://www.roblox.com/example-redirect |
| 范围 | 请求的范围，用空格分隔。使用 openid 范围来接收 ID 代币。使用 openid 和 profile 范围来获得更多用户信息。 | 是 | openid profile |
| response_type | 应用想要返回的凭据。默认是授权代码授予类输入。 | yes | none , code |
| prompt | 指定向用户显示哪些验证和同意页。某些屏幕对第三方应用程序至关重要，无法跳过。 | no | none , login , consent , select_account |
| nonce | 与客户端绑定代币的加密数字。 | no | <random_value_1> |
| 状态 | 一种不透明的值，防止跨站请求伪造，一种恶意攻击类型。授权后返回到应用程序。 | no | <app-provided-opaque-value> |
| code_challenge | 结果串将 code_challenge_method 应用到 code_verifier 。 | no | Base64-URL-编码字符串 |
| code_challenge_method | 应用于 code_verifier 的函数。 | no | S256 |
请求
Example Request of Directing to Authorization Flow
回应
调用此端点后，用户被重定向到指定的重定向 URL，其中包含授权代码在 code 查询参数中。授权代验证码：
- 有一个一分钟的生命周期。
- 只能兑换一次。
- 在使用一次后无效。
代币兑换
要获得允许访问 API 的代币，交换一个 授权代码 以获取一组机密代币。所有代币端点支持两种客户端验证类型：
- 带有授权头的 HTTP 基本认证方案：Authorization: Basic Base64 encoded(<client_id>:<client_secret>)。
- 客户端 ID 和秘密在请求体中作为参数。
以下列表描述了你从此端点收到的各种代币。
访问代币 - 代表创建者或用户对第三方应用程序的授权，以访问他们受保护的 Roblox 资源。它是指定特定范围、生命时间和其他访问特性的字符串。一旦 Roblox 授权服务器向应 App 发出访问代币，该代币：
- 有效期为 15 分钟。
- 在过期前可多次使用。
- 如果应用用户撤销授权，可以在过期之前无效化，如果应用用户撤销授权。
刷新代币 - 刷新授权会话。应用程序可以使用刷新代币获得一个新的代币集，该集包括一个访问代币、一个刷新代币和一个 ID 代币。刷新代币：
- 有效期为 90 天。
- 只能在过期刷新代币之前使用一次。
- 如果应用用户撤销授权，可以在过期之前无效化，如果应用用户撤销授权。
ID 代币 - 提供证明用户身份已被验证的证据。其内容取决于请求的范围，可包含用户的基本信息，包括用户的 Roblox 显示名称和用户名。身份证明代币仅用于身份验证目的，不提供访问任何 Roblox 资源的权限。
POST v1/token
使用授权代验证码获得一组代币。
请求
(x-www-form-urlencoded)
| 钥匙 | 值 |
|---|---|
| 代码 | <authorization code> |
| 代码验证器 | <pkce code verifier value> |
| 授予类型 | 授权代码 |
| 客户 ID | <client_id> |
| 客户秘密 | <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)
| 钥匙 | 值 |
|---|---|
| 代币 | <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 用户名和显示名称，因此不要将它们用作唯一标识来指向您应用程 App 上的用户。
| 索赔 | 描述 |
|---|---|
| sub | Roblox 用户 ID。 |
| name | Roblox 显示名称。 |
| 昵称 | Roblox 显示名称。 |
| preferred_username | Roblox 用户名。 |
| created_at | Roblox 帐户创建时间作为 Unix 时戳。 |
| 个人资料 | Roblox 帐户个人资料 URL。 |
| 图片 | Roblox 虚拟形象头部图像。如果虚拟形象头部图像尚未生成或已被审核，可以为 null |
带有个人资料范围的示例用户
{
"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"
}
发现
开放 ID 连接（OIDC）发现文档是一个 JSON 文档，包含关于开放云配置详细信息的元数据，包括支持的身份相关范围和声明列表。您可以使用它来动态发现关于开放云 OAuth 2.0 终端和配置的信息，例如授权端点、代币端点和公共钥匙设置。
从发现文档 URI 中恢复和获取发现文档后，您可以手动检查响应中的字段以验证信息，或者您可以创建自己的自定义库映射到响应示范中的字段来自动化工作流程。
GET .well-known/openid-configuration
回应
所有发现文档响应都遵循以下示例响应的同一 schema。
以下所有范围和声称并不都适用于第三方应用创建者，因为一些仅限官方 Roblox 应用使用。
示例发现文档响应
{
"issuer": "https://apis.roblox.com/oauth/”,
"authorization_endpoint": "https://api.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/资源",
"userinfo_endpoint": "https://apis.roblox.com/oauth/v1/userinfo"，
"jwks_uri": "https://apis.roblox.com/oauth/v1/certs”，
"registration_endpoint": "https://创建 or 创作reate.roblox.com/ashboard/credentials",
"service_documentation": "https://创建 or 创作reate.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"
]
}