How to use the Roblox web API endpoints?
Greetings everyone!
In this tutorial I will be explaining how you can use the Roblox web API endpoints. I decided to create this post because I know from personal experience I found it hard to learn how to use the API endpoints due to there being no real tutorial on how to use them and also no real YouTube videos; the only videos on YouTube is how to use things like Noblox.js which is good but not if you want to learn how to use the API directly so I want to give my knowledge to make it easier for everyone.
Quick Note: This tutorial is for how to use the Roblox API endpoints through the use of the Roblox security cookie. This tutorial is not for the Roblox Open Cloud (the Open Cloud works differently and does not use the Roblox security cookie). This tutorial will also contain examples off how to use the Roblox API endpoints which are written using JavaScript (in the runtime environment node.js). Sending requests will be different for different programming languages however the basic idea of how to use the Roblox API endpoints are the same.
Contents of Tutorial
- Issues with using the Roblox API endpoints
- Roblox API authentication
- How to send get requests
- How to send post requests
- Quick over view of error handling
Please before using this tutorial learn how to send basic API requests before attempting to use this tutorial. Although it will explain how to use the API endpoints I will not be going into major details into how to send requests.
Issues with using the Roblox API endpoints:
In this section of the tutorial I will be going over two main issues you may encounter when using the Roblox APIs. These are that due to a quite recent update Roblox security cookie become invalid on change of the region your IP address is at and also changes Roblox does to there API endpoints don’t get announced very often.
As some of you may have seen if you use the Roblox API in any way at all currently it seems that when your IP region changes to a different one it will invalidate this cookie. This was a update that Roblox has done to reduce the amount of people having there accounts compromised due to that security cookie getting invalidated when used at a different region then the IP that created the cookie. This is a great update for Roblox account security but bad news for us devs who use hosting severs that are not on the same region then the cookie was created. A good way of fixing this issue is running your bot or what ever your using the API for on a server which is on the same region then the API was created at. There are other ways but I will not go into lots of details on this,
The next main issue is that Roblox does not often announce changes to the API endpoints. The reason for this is because the Roblox API endpoints are not officially supported for external use. The API endpoints are internal endpoints (the Open Cloud will be the supported API when they get it all complete). Roblox does sometimes announce changes like the recent one talking about the removal of some main API endpoints however this is not often announced. There is not much we can do untill the Open Cloud is complete which will be a very long time though for all the endpoints to be added to the Open Cloud.
API Authentication
I will next be explaining how you can authenticate a request. Unlike the Roblox Open Cloud where you use an API key when using the API endpoints in general at the current moment you will be required to use a Roblox security cookie to use some of the endpoints. What is a Roblox security cookie? I expect that everyone who is looking into using the Roblox API endpoints directly themselves would know what the security cookie is but if you do not understand it is basically what the cookie is used for authenticating that someone is logged into the website. Due to this we can use this to our advantage and use it as the way to authenticate requests. You only need to authenticate some requests (mainly POST, DELETE and PATCH requests) however some GET requests also require authentication. Below you can view how to get the Roblox cookie.
How to get Roblox security cookie:
After you have got the Roblox security you can use this to send requests. Quick note that you should not have your Roblox security in your main code but as something like an environment variable to keep it as secure as possible. You will then need to put this Roblox security cookie in your header of any Roblox API requests that require authentication. In the headder the cookie should be named “Cookie” and you also require “.ROBLOSECURITY=” in front of the security cookie.
Example taken from the Roblox API wiki:
Although we use the Roblox security cookie to authenticate requests we do also require to get something called a X-CSRF-Token. If we do not add the X-CSRF-Token and only have the Roblox security cookie then it will provide you a 403 status code with the error message of Token Validation Failed. The issue however is that X-CSRF-Token’s get auto get invalidated after a couple of minutes so due to this we need to get a new one ever so often. Lucky for us basically all requests that require authentication will provide you with a new X-CSRF-Token so due to this we can send the request with the X-CSRF-Token and if it is invalid then you can take the X-CSRF-Token from the invalid request and re-do the request. It is also highly recommend you save the X-CSRF-Token from a request and then only get a new one if the old one become invalid. By the way you should know this if you know how to send API requests but if the request is valid and works we should get a status code of 200 which means that the request was ok/valid.
Example taken from the Roblox API wiki:
If we do the above with the Roblox cookie and the X-CSRF-Token then we should be able to send a request which requires authentication. Can be annoying with the X-CSRF-Token but just remember if it become invalid get the new X-CSRF-Token from the request header of the invalid request and then send the request again. 
How to send get requests to the API endpoints
I will next be explaining how to send GET requests that do not require authentication. Now if you understand the basics of sending requests to API endpoints you should already know how to send get requests to the Roblox API that do not require any authentication at all. It is very easy to do and you just send the request with the required headers and other things that you have inside of a request. Below I will leave a very basic example using axios.
Example get request
const axios = require(`axios`).default; // Requreing the axios npm package
const GroupID = 14558534 // The group ID of the group we want
await axios.get(`https://groups.roblox.com/v1/groups/${GroupID}`) // The main request to the endpoint (for this API endpoint you need to add the group ID on the end)
.then(function (response) { // If the request is sucessfull then it should go into this area where we log the data to the console to show we have it
console.log(response.data)
})
.catch(await function (Err){ // If there is an error with the request we want to catch the error and get the status of the error
console.log(Err.response.status)
})
How to send a post request to the Roblox API endpoint
Again like the get request as long as you understand how to send post requests you should have no trouble sending a post request. All you really need is to know how to send post requests and understand how to authenticate the request which I have explained in this tutorial. If you understand how to authenticate the request it is as simple as sending the required things in the request with the authentication requirement (cookie and X-CSRF-Token) in the header of the request.
Example post request (have not tested it but you get the idea)
const axios = require(`axios`).default
const GroupID = 14558534 // The Roblox group
let xCsrfToken = ""; // The x-csrf-token
axios.post(`https://groups.roblox.com/v1/groups/${GroupID}/social-links`, {"type": "Facebook", "url":"https://www.facebook.com/Roblox", "title":"Roblox Facebook"}, {
headers:{
Cookie: `.ROBLOSECURITY=${cookie}`,
"x-csrf-token": xCsrfToken,
"Content-Length": "0"
}})
.then(function (response) { // If the request is sucessfull then it should go into this area where we log the data to the console to show we have it
console.log(response.data)
})
.catch(await function (Err){ // If there is an error with the request we want to catch the error and get the status of the error
console.log(Err.response.status)
})
Overview of error handling
I will not be going over this area that much due to there being lots of different possible errors that you can get but really you will just need to test around and see what errors you will get. Just a tip always check the status code but also the error message that you get. If the status code is 200 then you know that the request was sucessfull.
You can also check the error status codes here: HTTP response status codes - HTTP | MDN
Conclusion of tutorial
I hope that this tutorial has helped a bit to understand how to use the Roblox web API and also mainly how to authenticate request that require authentication. If you have any suggestions for me to add to this tutorial feel free to leave them in the comments (or direct message me here) and also if you have any questions or need any extra help that I have not included feel free to ask below and I will attempt to answer your questions.
I recommend reading about the API in the wiki for it as there is much info there: https://robloxapi.wiki/wiki/Main_Page
