Dokumen ini menggambarkan endpoint yang Anda panggil untuk mengimplementasikan alur kode otorisasi OAuth 2.0, serta endpoint lain yang berguna untuk mengimplementasikan autentikasi di aplikasi Anda.
URL Dasarhttps://apis.roblox.com/oauth
EndpointGET v1/authorizePOST v1/tokenPOST v1/token/introspectPOST v1/token/resourcesPOST v1/token/revokeGET v1/userinfoGET .well-known/openid-configuration
Otorisasi
GET v1/authorize
Mendapatkan otorisasi dari pengguna untuk melakukan autentikasi dengan akun Roblox mereka. Mengharapkan URL otorisasi yang valid yang dibangun dengan parameter yang ditentukan. Endpoint ini mendukung otorisasi PKCE.
Parameter kueri
| Nama | Deskripsi | Diperlukan | Contoh |
|---|---|---|---|
| client_id | ID klien aplikasi. | ya | 816547628409595165403873012 |
| redirect_uri | URL yang digunakan pengguna setelah menyelesaikan alur otorisasi. | ya | `https://www.roblox.com/example-redirect`` |
| scope | Ruang lingkup yang diminta, dipisahkan spasi. Gunakan ruang lingkup openid untuk menerima ID token. Gunakan ruang lingkup openid dan profile untuk mendapatkan informasi lebih lanjut tentang pengguna. | ya | openid profile |
| response_type | Kredensial yang ingin dikembalikan oleh aplikasi. Defaultnya adalah tipe grant kode otorisasi. | ya | none, code |
| prompt | Menyebutkan halaman autentikasi dan persetujuan yang ditampilkan kepada pengguna. Beberapa layar diperlukan untuk aplikasi pihak ketiga dan tidak dapat dilewati. | tidak | none, login, consent, select_account |
| nonce | Nomor kriptografis yang mengikat token dengan klien. | tidak | <random_value_1> |
| state | Nilai opak yang mencegah pemalsuan permintaan lintas situs, sejenis serangan jahat. Dilewatkan kembali ke aplikasi setelah otorisasi. | tidak | <app-provided-opaque-value> |
| code_challenge | String yang dihasilkan dari penerapan code_challenge_method pada code_verifier. | tidak | String yang terenkode Base64-URL |
| code_challenge_method | Fungsi yang diterapkan pada code_verifier. | tidak | S256 |
Permintaan
Contoh Permintaan Mengarahkan ke Alur Otorisasihttps://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
Respon
Setelah memanggil endpoint ini, pengguna akan diarahkan ke URL redirect yang ditentukan dengan kode otorisasi dalam parameter kueri code. Kode otorisasi:
- Memiliki masa berlaku satu menit.
- Hanya dapat ditebus sekali.
- Tidak valid setelah digunakan.
Pertukaran token
Untuk mendapatkan token untuk mengakses API, tukar kode otorisasi dengan satu set token rahasia. Semua endpoint token mendukung dua jenis autentikasi klien:
- Skema Autentikasi Dasar HTTP dengan header otorisasi: Authorization: Basic Base64 encoded(<client_id>:<client_secret>).
- ID klien dan rahasia dalam badan permintaan sebagai parameter.
Daftar berikut menggambarkan berbagai token yang Anda terima dari endpoint ini.
Token akses - Mewakili otorisasi dari pembuat atau pengguna untuk aplikasi pihak ketiga mengakses sumber daya Roblox mereka yang dilindungi. Ini adalah string yang menunjukkan ruang lingkup, masa berlaku, dan atribut akses lainnya. Setelah server otorisasi Roblox mengeluarkan token akses ke suatu aplikasi, token tersebut:
- Valid selama 15 menit.
- Dapat digunakan beberapa kali sebelum masa berlakunya habis.
- Dapat dinyatakan tidak valid sebelum masa berakhir jika pengguna aplikasi mencabut otorisasi.
Token penyegaran - Menyegarkan sesi otorisasi. Suatu aplikasi dapat menggunakan token penyegaran untuk mendapatkan set token baru, yang mencakup token akses, token penyegaran, dan ID token. Token penyegaran:
- Valid selama 90 hari.
- Hanya dapat digunakan sekali sebelum masa berlakunya habis untuk menyegarkan token.
- Dapat dinyatakan tidak valid sebelum masa berakhir jika pengguna aplikasi mencabut otorisasi.
ID token - Menyediakan bukti bahwa identitas pengguna telah diautentikasi. Isinya tergantung pada ruang lingkup yang diminta dan dapat berisi informasi dasar pengguna, termasuk nama tampil Roblox pengguna dan nama pengguna. ID token hanya untuk tujuan autentikasi identitas dan tidak memberikan akses ke sumber daya Roblox mana pun.
POST v1/token
Dapatkan satu set token dengan kode otorisasi.
Permintaan
(x-www-form-urlencoded)
| Kunci | Nilai |
|---|---|
| code | <kode otorisasi> |
| code_verifier | <nilai verifikasi kode pkce> |
| grant_type | authorization_code |
| client_id | <client_id> |
| client_secret | <client_secret> |
Contoh Permintaan Mengambil Tokencurl --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'
Respon
Contoh Respon Mengambil Token
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 899,
"scope": "universe-messaging-service:publish"
}
POST v1/token
Dapatkan satu set token dengan token penyegaran.
Permintaan
(x-www-form-urlencoded)
| Kunci | Nilai |
|---|---|
| grant_type | refresh_token |
| refresh_token | <refresh_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
Contoh Permintaan Token Penyegarancurl --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'
Respon
Contoh Respon Permintaan Penyegaran Token
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 899,
"scope": "universe-messaging-service:publish"
}
POST v1/token/introspect
Terima informasi tentang token. Memverifikasi apakah token saat ini valid dan belum kedaluwarsa. Berguna untuk validasi tanpa status. Gunakan hanya jika API yang Anda akses tidak memerlukan sumber daya, seperti API Aset, atau jika Anda hanya ingin melihat klaim tertentu dari token.
Permintaan
(x-www-form-urlencoded)
| Kunci | Nilai |
|---|---|
| token | <access_token>, <refresh_token> atau <id_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
Contoh Permintaan Introspeksi Tokencurl --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'
Respon
Contoh Respon Introspeksi Token
{
"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
Periksa apakah token dapat mengakses sumber daya tertentu dengan mendapatkan daftar sumber daya pengguna yang diberikan izin. Ini berguna untuk validasi bersifat status.
Permintaan
(x-www-form-urlencoded)
| Kunci | Nilai |
|---|---|
| token | <access_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
Contoh Permintaan Dapatkan Sumber Daya Tokencurl --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'
Respon
Nilai U dalam ids menunjukkan bahwa suatu ruang lingkup telah memberikan akses ke sumber daya yang dimiliki oleh owner yang memberikan otorisasi.
Contoh Respon Dapatkan Sumber Daya Token
{
"resource_infos": [
{
"owner": {
"id": "1516563360",
"type": "User"
},
"resources": {
"universe": {
"ids": ["3828411582"]
},
"creator": {
"ids": ["U"]
}
}
}
]
}
POST v1/token/revoke
Cabut sesi otorisasi menggunakan token penyegaran yang diberikan.
Permintaan
(x-www-form-urlencoded)
| Kunci | Nilai |
|---|---|
| token | <refresh_token> |
| client_id | <client_id> |
| client_secret | <client_secret> |
Contoh Permintaan Cabut Tokencurl --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'
Respon
200 OK dengan respon kosong
Informasi Pengguna
GET /v1/userinfo
Mendapatkan ID pengguna Roblox dan metadata pengguna lainnya.
Permintaan
Header otorisasi: Authorization: Bearer <access_token>
Contoh Permintaan Dapatkan Info Penggunacurl --location --request GET 'https://apis.roblox.com/oauth/v1/userinfo' \--header 'Authorization: Bearer eyjlflabtfl...4gxqYBG'
Respon
Anda dapat menggunakan nilai sub untuk mengidentifikasi pengguna secara unik. Pengguna dapat mengubah nama pengguna dan nama tampil Roblox mereka, jadi jangan gunakan mereka sebagai pengidentifikasi unik untuk merujuk ke pengguna di aplikasi Anda.
| Klaim | Deskripsi |
|---|---|
| sub | ID pengguna Roblox. |
| name | Nama tampil Roblox. |
| nickname | Nama tampil Roblox. |
| preferred_username | Nama pengguna Roblox. |
| created_at | Waktu pembuatan akun Roblox sebagai timestamp Unix. |
| profile | URL profil akun Roblox. |
| picture | Gambar headshot avatar Roblox. Dapat bernilai null jika gambar headshot avatar belum dihasilkan atau telah dimoderasi. |
Contoh Pengguna dengan Ruang Lingkup Profil
{
"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"
}
Contoh Pengguna Tanpa Ruang Lingkup Profil
{
"sub": "1516563360"
}
Penemuan
Dokumen Penemuan OpenID Connect (OIDC) adalah dokumen JSON yang berisi metadata tentang detail konfigurasi Open Cloud, termasuk daftar ruang lingkup dan klaim terkait identitas yang didukung. Anda dapat menggunakannya untuk menemukan informasi tentang endpoint dan konfigurasi OAuth 2.0 Open Cloud secara dinamis, seperti endpoint otorisasi, endpoint token, dan set kunci publik.
Setelah mengambil dan mendapatkan Dokumen Penemuan dari URI dokumen Penemuan, Anda dapat memeriksa bidang dalam respon untuk memverifikasi informasi, atau Anda dapat membuat pustaka kustom sendiri yang memetakan ke bidang dalam skema respon untuk mengotomatisasi alur kerja Anda.
GET .well-known/openid-configuration
Respon
Semua respon Dokumen Penemuan mengikuti skema yang sama dengan respon contoh berikut.
Contoh Respon Dokumen Penemuan
{
"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"
]
}