OAuth 2.0 認證

OAuth 2.0 認證是一個可能在未來版本中發生變更的測試功能。所有開放雲端端點也都支持 API 鑰匙驗證。

要完整實施指南和關於 OAuth 2.0 的資訊，包括樣本應用程App，請參閱 OAuth 2.0 總覽。

本文描述您呼叫以實現 OAuth 2.0 授權代碼流程的終端點，以及其他對於在應用程式中實現認證有用的終端點。

Base URL
https://apis.roblox.com/oauth

Endpoints
GET v1/authorize
POST v1/token
POST v1/token/introspect
POST v1/token/resources
POST v1/token/revoke
GET v1/userinfo
GET .well-known/openid-configuration

授權

GET v1/authorize

獲得使用者的授權，以使用其 Roblox 帳帳號進行驗證。期望使用指定參數構建的有效授權 URL。此端點支持 PKCE 授權。

查詢參數

名稱	說明	需要	範例
client_id	應用 App 式的客戶 ID。	yes	816547628409595165403873012
redirect_uri	用戶在完成授權流程後返回的 URL。	yes	https://www.roblox.com/example-redirect
範圍	要求的範圍，用空格分隔。使用 openid 範圍來接收 ID 代碼。使用 openid 和 profile 範圍來獲得更多使用者資訊。	yes	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-encoded 字串
code_challenge_method	應用於 code_verifier 的功能。	否	S256

請求

Example Request of Directing to Authorization Flow
https://apis.roblox.com/oauth/v1/authorize?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid&response_type=code&nonce=12345&state=6789

回應

呼叫此端點後，使用者將被重定向到指定的重定向 URL，並在 code 查詢參數中使用授權代碼。授權代碼：

有一分鐘的生命。
只能兌換一次。
使用一次後無效。

代幣交兌換

要獲得允許使用 API 的代幣，請將授權代碼交換為一組機密代幣。所有代幣端點支持兩種客戶認証類型：

使用授權頭的 HTTP 基本驗證方案：Authorization: Basic Base64 encoded(<client_id>:<client_secret>)。
客戶端 ID 和秘密在請求體中作為參數。

以下列表描述您從此端點接收的各種代幣。

存取代碼 - 代表創作者或使用者對第三方應用程式存取他們受保護的 Roblox 資源的授權。它是指定特定範圍、生命週期和其他存取特性的字串。一旦 Roblox 授權服務器向應用程 App 發出使用權代碼，代碼：
- 有效期為 15 分鐘。
- 在過期之前可以多次使用。
- 如果應用用戶撤回授權，可以在過期之前無效化，以免過期。
重新整理代幣 - 重新整理授權會作業。應用程式可以使用刷新代幣來獲得一組新的代幣，包括一個存取代幣、一個刷新代幣和一個身份代幣。重新整理代幣：
- 有效期為 90 天。
- 只能在到期前使用一次以刷新代幣。
- 如果應用用戶撤回授權，可以在過期之前無效化，以免過期。
ID 代幣 - 提供證明使用者身份已被認證的證據。內容取決於請求的範圍，可包含基本用戶資訊，包括使用者的 Roblox 顯示名稱和使用者名稱。身份標識代幣只用於身份驗證目的，不提供進入任何 Roblox 資源的訪問。

POST v1/token

使用授權代碼獲得一組代幣。

請求

(x-www-form-urlencoded)

鑰匙	值
code	<authorization code>
code_verifier	<pkce code verifier value>
grant_type	授權碼
client_id	<client_id>
client_secret	<client_secret>

範例獲取代幣請求
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=yCnq4ofX1...XmGpdx'

回應

範例獲取代幣回應
{
  "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>

範例重新整理代幣請求
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=Ujfstayclfdlbm...BGydlsnU' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

回應

範例重新整理代幣請求
{
  "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>

範例檢視代幣請求
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyjlflabtfl...4gxqYBG' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

回應

範例介觀代幣回應
{
  "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>

範例獲取代幣資源請求
curl --location --request POST https://apis.roblox.com/oauth/v1/token/resources' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyjlflabtfl...4gxqYBG' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

回應

值 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>

範例撤消代幣請求
curl --location --request POST https://apis.roblox.com/oauth/v1/token/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Ujfstayclfdlbm...BGydlsnU' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

回應

200 OK 使用空回應

使用者資訊

GET /v1/userinfo

取得 Roblox 使用者 ID 和其他使用者元數據。

請求

授權頭部 : Authorization: Bearer <access_token>

範例取得使用者資訊請求
curl --location --request GET 'https://apis.roblox.com/oauth/v1/userinfo' \
--header 'Authorization: Bearer eyjlflabtfl...4gxqYBG'

回應

您可以使用 sub 值來唯一標識使用者。使用者可以變更他們的 Roblox 使用者名稱和顯示名稱，因此不要使用它們作為 App 用程式上的使用者識別符來引用使用者。

領取	說明
sub	Roblox 使用者 ID。
name	Roblox 顯示名稱。
暱稱	Roblox 顯示名稱。
preferred_username	Roblox 用戶名。
created_at	Roblox 帳戶創建時間作為 UNIX 時間戳。
個人檔案	Roblox 帳戶個人檔案 URL。
照片	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"
}

發現

開放 ID 連線(OIDC)發現文件是一個 JSON 文件，包含開放雲端配置細節的元數據，包括支持的身份相關範圍和主張清單。您可以使用它來動態發現開放雲端 OAuth 2.0 端點和配置的資訊，例如授權端點、代幣端點和公共鑰匙設定。

從發現文件 URI 中恢復和擷取發現文件後，您可以手動檢查回應中的欄位以驗證信息，或者您可以創建自己的自訂圖書庫映射到回應欄位來自動化您的工作流程。

GET .well-known/openid-configuration

回應

所有發現文件回應都遵循以下示例回應的相同 schema。

以下所有範圍和主張並不都適用於第三方應用程式創作者，因為一些只能由官方 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/資源",
  "userinfo_endpoint": "https://apis.roblox.com/oauth/v1/userinfo"，
  "jwks_uri": "https://apis.roblox.com/oauth/v1/certs"，
  "registration_endpoint": "https://建立、創作reate.roblox.com/ashboard/credentials"，
  "service_documentation": "https://建立、創作reate.roblox.com/docs/reference/雲端",
  "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"
  ]
}

查詢參數

請求

回應

請求

回應

請求

回應

請求

回應

請求

回應

請求

回應

請求

回應

回應

此頁面