How to generate a .ROBLOSECURITY token from Quick Login

Resources Community Tutorials
#1

This guide explains the full process of authenticating an account through Quick Login, and logging it out again.

It is strongly advised to use OAuth through Open Cloud, but this guide covers APIs that aren’t under that umbrella, or if you want to make a more quick and dirty script for a one time patch.

Security Considerations

Before I continue with this guide, there are some considerations you should be aware of:

  1. If you dont intend to persist the token after you’re done with the script and you’ve logged in, always log out of the account, even if it errors.
  2. Use a strong testing system when implementing your APIs.
  3. Unless you absolutely need a .ROBLOSECURITY, using OAuth and Open Cloud is probably better

Introduction

Roblox’s Quick Login is a protocol for quickly logging into Roblox on unauthenticated sessions on sessions that are authenticated. This protocol is easy to implement in a third-party application or script if you need an authentication token.

The protocol works by creating a code, then periodically calling an API with the code to get an update status. This code will eventually return a message (if validated) that then signals you can log in.

This may be a better solution than getting the user to simply copy their .ROBLOSECURITY token from their browser.

HTTP Notes

All HTTP requests must send a Content-Type header of application/json for the APIs to work correctly, some web frameworks do this automatically, but its up to you to make sure.

Cross Site Request Forgery

Cross Site Request Forgery is a security exploit, Roblox implements a tactic to prevent this, many Roblox APIs requires a special handler to ensure noting suspicious is going on with the request.

These APIs requires a special header called x-csrf-token, this can be fetched by observing a failed response for the same header, if it’s present, you should attach the x-csrf-token from the response headers, and attach it to the request headers.

Roblox’s own X-CSRF implementation can be viewed on the several API docsites, which contain it in unobfuscated JavaScript. Any APIs that require a CSRF token, we’ll mark it with XCSRF METHOD, so for example, XCSRF POST.

Creating a token

The first step in the protocol, is fetching the token, this is done by sending a POST request to https://apis.roblox.com/auth-token-service/v1/login/create. Although this API is marked as POST, no body is sent.

You’ll be given a JSON response, two keys here are of note:

{
  "code":"",
  "status":"Created",
  "privateKey":"",
  "expirationTime":"",
  "imagePath":""
}

You should store the code and privateKey values, these are used to perform the actual login attempt. You should also keep note of the expirationTime, as if this elapses, the code and privateKey will no longer work. (This can easily be handled if you still want to attempt a login.)

The status key is used to track the current status of the token, this is also returned by the status API.

Currently, the following values are observed for this key:

  • Created - token was created, this is also returned by the Status API if nothing changes.
  • UserLinked - token has been inputted by a user, but hasn’t approved or cancelled the request yet.
  • Cancelled - token was inputted by a user, but was cancelled. This invalidates the current token.
  • Validated - token was authorised by a user, this marks the code and privateKey as ready to login with.

From here, you should then occassionally call another API to check the status of the API.

Checking the status of the token

Send a POST request to https://apis.roblox.com/auth-token-service/v1/login/status to get the current status of a generated token.

You should attach the following body to fetch status of a token:

{
  "code": "",
  "privateKey": ""
}

Both values here should be self-explanatory.

You’ll receive the JSON response of the following:

{
  "status":"Created",
  "accountName":null,
  "accountPictureUrl":null,
  "expirationTime":""
}

Unless you recieve a response of Cancelled or Validated, you should continue to request this API periodically. Roblox’s own implementation triggers it every 3-5 seconds.

UserLinked and Validated send the first two characters of the username of the user attempting to authenticate, with the remaining space being hidden with asterisks, for example: metatablecatmaid becomes me**************

accountPictureUrl currently always returns null, regardless of the status value, but this may change in the future. This post will be updated if this changes.

REMARK: 400 Response / body = "CodeInvalid"

If a code doesn’t exist, or expires, this response will return a 400 error, with the plaintext body "CodeInvalid" (including the double quotation marks), if this case happens, assume the status key is Cancelled and handle it that way.

Authenticating

When the status key returns Validated, you should then attempt the actual login. This is done through the API XCSRF POST https://auth.roblox.com/v2/login.

You should send the following JSON request to attempt a login:

{
  "ctype":"AuthToken",
  "cvalue":"",
  "password":"",
}

cvalue should be set to the code, and password should be set to the privateKey.

There’s an additional key here marked as secureAuthenticationIntent, but this is used for hardware-based authentication, if you’re authenticating a desktop application, such as a command shell, it’s not required.

If the login request is successful, you’ll have a new .ROBLOSECURITY cookie ready to go in one of the Set-Cookie response headers.

UNLESS YOU INTEND TO STORE THIS COOKIE FOR FUTURE USAGE, MAKE SURE TO LOGOUT THE CLIENT WHEN FINISHED

Cancelling a Quick Login attempt

If you instead choose to not go through with the quick login for whatever reason, you should invalidate the currently existing token. This is done with the API POST https://apis.roblox.com/auth-token-service/v1/login/cancel

All that needs to be sent is the code of the currently active token for it to be invalidated:

{"code": ""}

After this, the token can no longer be used.

Logging Out

When you’re done with a .ROBLOSECURITY cookie, you’ll want to log it out for security reasons.

Note: i’m unsure if this request is actually XCSRF POST, handle as if it is.

Logging out a client is handled with the API XCSRF POST https://auth.roblox.com/v2/logout. Nothing needs to be sent in the body, as long as the correct .ROBLOSECURITY is passed to the response, it will be logged out and can no longer be used.

Example Implementation

An implementation of QuickLogin can be viewed here. This is not the best implementation of this by far, but its a good starting point.

3 Likes