Roblox Oauth

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.

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.

Instructions

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

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

8. 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.

9. 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.

10. 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.

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.

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.

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.

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.

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.

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.

Cloud Auth Related Error Guidance

Key Concepts

• Roblox OAuth failures can happen in the browser redirect step, token step, or later when bearer tokens hit Open Cloud endpoints.
• Open Cloud error formats vary across v1, v2, and gateway layers.
• Scope problems and resource-authorization problems are related but not identical.
• OAuth helper endpoints such as token/introspect and token/resources are useful for narrowing the failure source.

Rules

• Start by locating the failing stage: authorize, callback, token exchange, refresh, or resource API call.
• Treat missing or mismatched state as a flow integrity failure, not a retriable API error.
• Treat INVALID_ARGUMENT as malformed request data first.
• Treat INSUFFICIENT_SCOPE or PERMISSION_DENIED as missing scope or missing permission first.
• Treat RESOURCE_EXHAUSTED or HTTP 429 as quota or rate pressure and back off.
• Treat token introspection as activity checking only; use token/resources when resource access is uncertain.

Patterns

Failure triage

redirect failed?
-> inspect error and error_description from callback

token request failed?
-> verify grant_type, code or refresh token, client auth, redirect URI, and PKCE verifier

API call failed with bearer token?
-> verify scope, token expiry, and resource grant coverage

Common Open Cloud auth errors

• INVALID_ARGUMENT:
• malformed form body
• bad redirect URI
• bad or reused authorization code
• PERMISSION_DENIED or INSUFFICIENT_SCOPE:
• missing endpoint scope
• user lacks access to the target resource
• token does not cover the target universe, group, or user resource
• RESOURCE_EXHAUSTED:
• too many requests
• UNAVAILABLE:
• transient platform issue; retry carefully if safe

Useful checks

• Expired access token: refresh the session.
• Refresh fails after prior successful refresh: check whether the old refresh token was mistakenly reused.
• Introspection says active but API still fails: inspect scopes and call token/resources.

Examples

• Callback returns error and error_description: stop and surface the authorization failure cleanly to the user.
• Bearer token gets 403 on a universe action: verify both the endpoint scope and that the authorizing user granted that universe resource.
• Refresh path breaks after one success: likely refresh-token rotation was ignored and stale storage is being reused.

OAuth Development Guide

Key Concepts

• Roblox supports authorization code flow with and without PKCE.
• PKCE adds a per-request code verifier and derived code challenge.
• state protects the callback against CSRF-style request forgery.
• nonce binds identity information when using OIDC claims.
• The callback may carry either success parameters or OAuth error parameters.

Rules

• Use PKCE for all clients and require it for public clients.
• Generate a fresh code_verifier, code_challenge, and state for every authorization request.
• Use only unreserved characters for code_verifier and keep it 43 to 128 characters long.
• Set code_challenge_method=S256.
• Verify state before trusting the returned authorization code.
• Treat callback errors as first-class control flow, not rare exceptions.

Patterns

Authorization URL construction

GET https://apis.roblox.com/oauth/v1/authorize
  ?client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &scope=<space-delimited scopes>
  &response_type=code
  &state=<random value>
  &code_challenge=<pkce challenge>
  &code_challenge_method=S256

Callback handling

• Success path: read code, verify state, continue to token exchange.
• Failure path: read error, error_description, and state, then stop or recover safely.

Token exchange request

POST /oauth/v1/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=<authorization code>
client_id=<client_id>
code_verifier=<original verifier>

Token storage pattern

• Keep access tokens short-lived in memory or short-duration server storage.
• Keep refresh tokens only in trusted server-side storage.
• Replace the stored refresh token after every successful refresh.

Examples

• Browser app: generate PKCE client-side, send the code to a trusted backend, and let the backend store refresh tokens.
• Server-rendered app: keep the secret and refresh token in backend storage, then issue an app session cookie to the browser.

OAuth Overview

Key Concepts

• Roblox Open Cloud OAuth 2.0 is for delegated access to protected Roblox resources.
• The main roles are resource owner, client, authorization server, and resource server.
• Roblox supports authorization code flow and authorization code flow with PKCE.
• PKCE is recommended for all clients and required for public clients.
• Roblox also layers OpenID Connect on top of OAuth for user identity claims.
• Users must be 13+ to authorize apps.
• Developers must be ID verified to register and publish OAuth apps.

Rules

• Use authorization code flow for Roblox OAuth integrations.
• Treat browser and mobile apps as public clients.
• Never expose a confidential client secret to public code or public storage.
• Add openid if the app needs an ID token.
• Add profile only when the app needs richer user profile claims, and only alongside openid.

Patterns

Client classification

• Confidential client: backend-capable app that can securely hold secrets.
• Public client: mobile or browser app that cannot safely hold secrets.

OAuth plus OIDC

• OAuth access token: authorizes Open Cloud API access.
• ID token: proves identity and carries claims; it does not grant API access.

High-level flow

Register app
-> send user to /oauth/v1/authorize
-> receive code on redirect
-> exchange code at /oauth/v1/token
-> call APIs with bearer access token
-> refresh or revoke later as needed

Examples

• A creator authorizes a third-party dashboard to manage a universe without sharing Roblox credentials.
• A mobile companion app uses PKCE and asks only for openid plus the one API scope it actually needs.

OAuth Reference

Key Concepts

• The OAuth base URL is https://apis.roblox.com/oauth.
• Core endpoints are authorize, token, introspect, resources, revoke, userinfo, and the OIDC discovery document.
• Authorization codes are short-lived and single-use.
• Access tokens are bearer tokens for API access.
• Refresh tokens renew the session and rotate.

Rules

• Send users to GET /v1/authorize to start the flow.
• Exchange codes or refresh tokens at POST /v1/token.
• Use POST /v1/token/introspect for token activity and claims, not resource authorization.
• Use POST /v1/token/resources to check which resources the token can access.
• Use POST /v1/token/revoke with the refresh token to end the authorization session.
• Use GET /v1/userinfo only with a bearer access token.

Patterns

Token lifetimes and reuse

• Authorization code:
• valid for 1 minute
• redeemable once
• Access token:
• valid for about 15 minutes
• reusable until expiry or revocation
• Refresh token:
• valid for about 90 days
• single-use for refresh

Introspection versus resources

• introspect: "Is this token active and what claims does it carry?"
• resources: "What Roblox resources did the user actually grant access to?"

OIDC discovery

• Use GET /.well-known/openid-configuration to discover:
• authorization endpoint
• token endpoint
• introspection endpoint
• revocation endpoint
• userinfo endpoint
• supported scopes and claims

Examples

• Identity-only check: request openid, exchange the code, then call /v1/userinfo.
• Resource-aware app: after token exchange, call /v1/token/resources before showing a universe picker or action UI.

OAuth Registration

Key Concepts

• Roblox app registration happens in Creator Dashboard under OAuth 2.0 Apps.
• Registration creates a client ID and a client secret.
• The client secret is shown once; after that, it must be regenerated if lost.
• Apps begin in private mode with a limit of 10 unique users.
• Public distribution requires app review and publication.
• Redirect URLs, scopes, and public-facing app metadata are part of app configuration.

Rules

• Register apps only for individual accounts or groups you own.
• Store the secret immediately and securely after app creation.
• Request the minimum set of scopes required by the app.
• Keep the scope set aligned to a single app category under Roblox policy.
• Use exact redirect URLs that match one of the allowed forms.
• Reauthorize users after adding or changing scopes.

Patterns

Redirect URL rules

• Allowed:
• https://example.com
• http://localhost:3000
• https://localhost:3000
• custom schemes such as my-app://callback
• Limits:
• up to 10 redirect URLs
• each URL up to 256 characters

Registration workflow

Create App
-> capture client ID and secret
-> add description and links
-> add scopes
-> add redirect URLs
-> test in private mode
-> submit for review when ready

Edit behavior

• Changing general info or redirect URLs does not force reauthorization.
• Changing scopes requires new authorization for the new permission set.

Examples

• Local web app: add http://localhost:3000/oauth/callback.
• Production site plus staging site: use two separate HTTPS redirects.
• Public app iteration: clone the public app into a private app for safe testing before resubmission.

OAuth Sample App

Key Concepts

• Roblox provides a Node.js sample app for OAuth 2.0.
• The sample uses authorization code flow without PKCE, so it is suitable only for confidential clients.
• The sample demonstrates localhost redirects, environment-variable configuration, token storage, and a simple authenticated action.
• The sample fetches the OIDC configuration dynamically.

Rules

• Do not copy the sample's non-PKCE flow into a public client.
• Keep client credentials in environment variables, not in source files.
• Ensure the localhost port matches the registered redirect URL.
• Treat the sample as an integration pattern, not a justification to skip current best practices like PKCE.

Patterns

Local development setup

• Register scopes:
• openid
• profile
• only the API scope the sample action needs
• Register redirect:
• http://localhost:3000/oauth/callback
• Set environment variables:
• ROBLOX_CLIENT_ID
• ROBLOX_CLIENT_SECRET
• optional ROBLOX_PORT

What the sample does

start Express server
-> fetch OIDC configuration
-> build OAuth client
-> redirect user to login
-> handle callback
-> store tokens in cookies
-> call an authenticated Open Cloud action

Safe adaptation pattern

• Keep the sample's environment-variable and localhost wiring.
• Replace non-PKCE pieces with PKCE if building a modern production integration.

Examples

• Quick local proof of concept: use the sample structure to validate redirect handling and token exchange.
• Production migration: preserve the route structure, but move to PKCE and server-side session management.

Risk Level Reference

Key Concepts

• Roblox classifies Open Cloud endpoints into low, medium, high, and critical risk levels.
• These levels are used in OAuth-related "try it out" experiences and warn about endpoint sensitivity.
• Higher risk usually means more destructive or less reversible actions.
• Critical-risk endpoints are not available through "try it out."

Rules

• Use risk level as a least-privilege design signal when choosing scopes.
• Be more conservative when an app requests scopes that unlock medium- or high-risk operations.
• Treat high-risk and critical operations as requiring stronger product justification and clearer user consent.
• Do not assume risk level replaces endpoint-by-endpoint review.

Patterns

Risk meanings

• Low:
• usually read-oriented or low-impact
• informational warning only
• Medium:
• can create, update, or access private data
• confirmation warning applies
• High:
• destructive or hard-to-reverse operations
• stronger warning before use
• Critical:
• highly sensitive account or privacy impact
• "try it out" disabled

Scope review heuristic

requested feature
-> endpoint set
-> scope set
-> endpoint risk level review
-> keep only the least powerful scope set that satisfies the feature

Examples

• Read-only profile helper: likely low-risk scope set.
• Universe mutation tool: medium or high-risk surface, so minimize scopes and tighten who can authorize it.
• Delete-capable admin tool: require explicit justification and avoid bundling those permissions into unrelated features.

Scopes Reference

Key Concepts

• Scopes define what an OAuth token is allowed to do.
• Roblox has identity scopes such as openid and profile, plus API-specific scopes for Open Cloud endpoints.
• Some endpoints require multiple scopes.
• The local OpenAPI artifact exposes required scopes through x-roblox-scopes and OAuth security metadata.

Rules

• Request only the scopes the app needs right now.
• Add openid when an ID token or stable user identity is required.
• Add profile only when profile claims are needed, and only with openid.
• Check endpoint-level scope requirements before finalizing the consent screen.
• Reauthorize users after changing scopes.

Patterns

Scope selection workflow

feature list
-> endpoints the app will call
-> required scopes for each endpoint
-> deduplicate
-> remove unused scopes
-> register only the final minimum set

Identity scope choices

• openid: stable user ID and ID token.
• openid profile: richer user metadata from userinfo.

Local scope lookup pattern

• Use sources/creator-docs/reference/cloud/openapi.json.
• Check x-roblox-scopes near the target operation.
• Confirm whether the endpoint exposes OAuth support metadata in the security section.

Examples

• User profile display: openid profile.
• User-authorized inventory access: include the user-facing inventory read scope only if the feature actually needs private inventory visibility.
• One action endpoint plus identity: openid plus the exact action scope, not a broad unrelated scope set.