How it works

About these notes

None of this is documented by Rockstar. I read it from the Social Club website's scripts, the overlay's scripts and the game's own code, and checked it against the live services. Any of it can change without notice.

The game's encryption keys and a few problems still pending with Rockstar are left out on purpose.

Services

Notes

• The website session and the ROS session are separate, and tokens from one are not accepted by the other. One sign-in can give both, though (below).
• The website API doesn't reject unknown query parameters. A wrong parameter name has no effect and gives no error, so every filter has to be checked by comparing results.
• Some limits are enforced without an error: invalid jobs are dropped from a playlist, job search results past the 10,000th can't be paged to, and a lobby closed by its host is still advertised.
• The website API allows about 30 searches back to back. The 31st answers 429, with no header saying how long to wait, and it clears after about 30 seconds. The limit is per address, not per account: right after a 429 the same search signed out got a 429 too. Measured

Sign-in

Website

There are two authorize entry points, and only one of them gives a token that can be renewed: Measured

Renewal:

POST https://socialclub.rockstargames.com/connect/refreshaccess
X-Requested-With: XMLHttpRequest
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Cookie: <the cookies left by the sign-in>

accessToken=<current token>

Sent with the token alone, without the sign-in cookies, it answers 401. Measured

Game (ROS)

ROS only accepts sessions obtained the way the Rockstar Games Launcher obtains them. Tickets from an email and password (CreateTicketSc3) are refused with NotAllowed/Password. Measured

Step 1: the launcher bridge

Inside the launcher, the sign-in page talks to the launcher through two functions on window, rgscQuery and rgscAddSubscription. Each takes an object with method, params and an onSuccess callback. In a normal browser they're missing and the page can't finish. These are the answers the page needs: Read

The device fingerprint is an object of five strings, in this order: device_name, machine_name, os_version, volume_serial, cpu_info. The launcher fills them in from the machine. SocialClub Plus sends its own name as the device and machine, and a random id kept per install for the serial and CPU, so the sign-in shows up as SocialClub Plus and not as the launcher. The page runs its own bot checks, and the password only goes into Rockstar's form.

Step 2: the gateway

GET https://rgl.rockstargames.com/api/connect/gateway?code=<authCode>&fingerprint=<state, URL-encoded>
X-Requested-With: XMLHttpRequest
Origin: https://rgl.rockstargames.com
Referer: https://rgl.rockstargames.com/
Cookie: <the sign-in window's cookies for rgl.rockstargames.com, if any>

The state is the fingerprint wrapped as {"fp": {...}}, with one space after the colon, as the launcher writes it. The same string goes with every ticket request and has to match. The JSON answer holds ScAuthToken (164 characters) and RememberedMachineToken. A ScAuthToken keeps minting tickets for days, one about 8 days old still worked. Measured

Step 3: the ticket

POST https://gta5-prod.ros.rockstargames.com/gta5/11/gameservices/auth.asmx/CreateTicketScAuthToken2
User-Agent: ros <encoded version string>
SCS-MFAMachineFingerPrint: <the state from step 2>
Content-Type: application/x-www-form-urlencoded; charset=utf-8

<the form, encrypted>

The version string is e=1,t=gta5,p=<platformName>,v=11. The User-Agent sends it as ros followed by the Base64 of four bytes 0xCD and then each byte of the string XORed with 0xCD. A GET, or platformName=pc, doesn't work. Measured

The platform name, the key and the platform in the User-Agent must agree, otherwise the answer is DoesNotMatch/TitleInfo. The XML answer holds Ticket, SessionKey, SessionTicket, CloudKey, PlayerAccountId, RockstarId, Privileges, Services (a host per service) and SecsUntilExpiration (86,399, so one day). Measured

One ROS session per account. A new ticket invalidates the previous one (AuthenticationFailed/DupLogin), and a game running on that account is signed out of GTA Online. Measured

Renewing it from a ticket

A live ticket can make a new ScAuthToken with socialclub.asmx/CreateScAuthToken on prod.ros, fields ticket, audience, ttlminutes and userdata (may be empty). The token comes back in <Result>. The old Social Club SDK does exactly this after signing in, with audience Game and 30 days, and signs in with that token the next time. Read A token made this way with 30 days minted a working Enhanced ticket. Measured Note that GetScAuthToken looks similar but gives a web-linking token that the ticket calls refuse.

So the launcher sign-in can be kept alive without the password, but only by minting a ticket, which ends the account's GTA Online session anyway.

One sign-in for both

The launcher's sign-in leaves the website's session behind too. Right after it, the browser profile holds an rsso-<suffix> cookie, and opening /connect/authorize/socialclub in that profile gives a BearerToken for the same account in about 2 seconds, with no form. Measured

It only works that way round. After the website's own sign-in, the launcher's page still asks for the password, and the ScAuthToken inside the website token's claims (scAuth.ScAuthToken, 160 characters) is refused for a ticket with AuthenticationFailed/ScAuthToken. Measured That's why the app's one sign-in is the launcher's.

The launcher sign-in itself mints no ROS ticket, so signing in doesn't end a GTA Online session. Only the first ticket does.

Game requests

Every ROS call, the ticket request included, sends its form encrypted and gets its answer encrypted. The scheme is the one in FiveM's open source code (ros-patches-five), and the app follows it line by line. Each build of the game has its own platform key, built into the game. The keys are not given here. Read

The platform key

A Base64 string. Decoded, byte 0 isn't used, bytes 1 to 32 are an RC4 key, and bytes 33 to 48 and 49 to 64 are two 16-byte keys, here called the mask key and the hash key. Both are stored encrypted with that RC4 key, each with a fresh RC4 state.

The form

Fields sorted by name in byte order, written as name=value and joined with &. Values are encoded as UTF-8: letters, digits and - _ . ~ stay as they are, a space becomes +, and every other byte becomes %xx in lowercase hex. Calls made with a ticket carry it in the ticket field.

Encrypting a request

1. Pick 16 random bytes: the request key.
2. Write the request key XORed with the mask key. These are the first 16 bytes of the body.
3. With a ticket, XOR the request key with the first 16 bytes of the ticket's SessionKey (Base64). The ticket request itself has none, and the request key stays as it is.
4. Encrypt the form with RC4 under the request key, and append it.
5. Append a 20-byte trailer, computed over everything written so far followed by the hash key: SHA-1 without a ticket, HMAC-SHA1 keyed with the request key with one.

Reading an answer

The first 16 bytes, XORed with the mask key (and with the session key, for a call made with a ticket), are an RC4 key. One RC4 stream then runs over the rest. Bytes 16 to 19 give a block size, big-endian. From byte 20 on, the answer comes in pieces of the block size plus 20 bytes: the block, then a 20-byte trailer that is skipped. The last piece can be shorter. Inside there's XML. An error raised by the server itself, and not by the service, comes back as plain text.

Calls made with a ticket

They carry four more headers. Measured

Every ROS host answers over https with a valid certificate. A wrong key gives an answer that can't be decrypted, while an error like NotAllowed/… or InvalidArgument/<field> means the server did read the request. Measured

Website API

Host https://scapi.rockstargames.com. Every call carries X-Requested-With: XMLHttpRequest, and the bearer token when signed in.

Access without a token

Signed out, the website sends X-AMC: true (allow mature content) after its age gate. Signed in, it leaves it out. Read

Measured

Job search

GET /search/mission?title=gtav&platform=pcalt&missionType=race&subType=landrace&sort=likes&searchTerm=&pageIndex=0&pageSize=30

Measured

• The dates are on two different axes. The presets (today, last7 and so on) filter on rootCreatedDate, when the job was first published. A custom range filters on createdDate, the date of the current version, which for an updated job is its last update. I didn't find a custom range on the first publication. Measured
• The website writes a crew filter as crew_<id> in its own address, but the API only filters with the split form, filter=crew&crewId=<id>.
• community and rockstarVerified ignore the platform and return jobs of every build. Measured
• No result past the 10,000th can be fetched: at 30 per page, page 332 answers and 333 returns 500.
• The answer has three collections, items, users and crews, linked by id. Signed in, each item carries bookmarked and played for the account.
• There's no sort direction, no player range, no rank, no vehicle class and no language filter. Each was tried with names that would change the result, and all were ignored. POST answers 405. Measured
• A job's page on the website is /job/gtav/<id>. The id is the same in playlists and on the content server.

Job details

GET /ugc/mission/details?title=gtav&contentId=<id>

Returns what the website's job page shows, plus content.data.mission, a trimmed copy of the creator file. Signed in, it adds liked, played, bookmarked, and lastPlayed for a job the account has played. Measured

Crews, players, photos

Measured

Search by area

The job search has a map zone filter, area=<zone code>, which the website's script accepts but its jobs page has no control for. It returns the jobs whose meta.loc holds that code exactly. meta.loc is a list of zones the game writes into the creator file when the job is published (Job files). Measured

• Races: the zones of the checkpoints, minus the zone the race starts in, even when later checkpoints are in it. So a race that only starts in an area isn't found by that area, and a race entirely inside its start zone has none. Measured
• Other modes: usually the zone they start in. Measured
• The codes are the game's zone names in upper case, cut to seven characters (BANHAMC, not BANHAMCA). One per call, case-sensitive, and an unknown code gives 0. 93 codes find jobs. Measured
• The golf course is spelled two ways: older jobs say GOLF, newer ones golf, and they're different jobs. A search for the golf course takes both calls.
• Outside every zone (high in the sky, the Arena War arena, Cayo Perico) a job gets SanAnd, written just like that.

To place a point in a zone the game takes the smallest box by volume among the boxes around it. Read The app reads the boxes from the game's files and draws its map with the same rule (without the height, since the map is flat), and it matched the meta.loc of 29 real races checkpoint by checkpoint. Measured That's why a tunnel or a creek can be a zone of its own.

Bookmarks

Each platform has its own list. The newer generation's list includes the older one's: pcalt includes pc, ps5 includes ps4, xboxsx includes xboxone. Measured

platformType: Measured

• A PC job takes its own platform, pc or pcalt.
• A console job, from an account that plays on PC: any platform name returns 500, while an empty value is accepted and lands on that console's list. A player reported the empty value failing on their account too.
• The website sends the job's own platform for every job. Read An account that plays on that console probably accepts it. Assumed

The list is a search, so it counts against the same limit of about 30 searches (Notes). A player with about 1,000 bookmarks hit the 429 reading all six lists. The app now skips an older generation's list when the newer one already has all of it, and spaces its reads. Measured

Job files

A job's full creator file, the data the game loads to run it, is public:

GET https://prod.cloud.rockstargames.com/ugc/gta5mission/{id}/0_{version}_{language}.json

mission holds sections under short internal names: gen, race, prop, dprop, veh, obj, weap, ene, zone, rule, … The fields that are settled:

Legacy and Enhanced

Write privilege follows the build played last. A ticket's Privileges list decides whether it can write. An account that had never played GTA Online on Enhanced got an Enhanced ticket with no privileges: reads worked, writes returned NotAllowed/Privilege. After one session on Enhanced, the Enhanced ticket was complete and the Legacy one empty. The same goes for lobby searches and photo uploads. Measured

Playlists

The website can read playlists but can't create them. They're created through ROS user content, ugc-gta5-prod.ros.rockstargames.com/gta5/11/gameservices/ugc.asmx, content type gta5playlist, with a ticket that has write privilege on the build. Measured

Playlist data:

{ "h2h": true, "list": [ { "cid": "<job id>", "name": "<job name>", "type": 2 } ] }

• list is the jobs, in play order. The game only reads cid. Read
• type is the family: 0 mission, 1 deathmatch, 2 race, 3 survival.
• h2h and ch: meaning not known.
• A playlist is published or a draft. A draft stays on the account and can't be played.
• Reads lag behind writes by a minute or two. A running game needs a restart to list a new playlist.
• The game plays jobs in list order unless Shuffle is on in the menu the playlist is started from, and that option starts off every time. Read

Measured

Playlist search

The website API has a playlist search that the website itself never calls (its playlist page is still the old one). It answers with no account and does more than the old page. Measured

GET /search/playlist?title=gtav&platform=pcalt&sort=plays&searchTerm=stunt&pageIndex=0&pageSize=30

Each playlist in the answer already lists its jobs, with name, picture, plays and likes, so one call gives the jobs of up to 30 playlists. A playlist's own page is /ugc/playlist/details?title=gtav&contentId=<id>, also without an account.

Lobbies

Open job lobbies and free roam sessions aren't exposed by the website. They're advertised in ROS matchmaking, mm-gta5-prod.ros.rockstargames.com, and a search needs a ticket with privileges on the build.

Advertised attributes

Measured

• Players in a job lobby are the job's maximum (gen.num in its details) minus the free places. In free roam another attribute looks like the player count (up to 32), not checked against a real session. Assumed
• No call turns an activity id into a job. To name a lobby's job you hash known job ids until one matches. An index of every Enhanced job (about 3.5 million) named every open race lobby in a sample. Measured

Discriminator bits

Read bit 15: Measured

Joining

Joining is done by the game client, peer to peer, and GTA V has no launch option that targets a job or a session. Read When a player starts a job, the game looks for an open lobby with the same activity id for about 60 seconds before hosting one. Read So starting a job from the bookmarks while a lobby of it is open should join that lobby, but I haven't seen it happen yet. Assumed

Profile picture

The profile picture is set through the in-game overlay's API, on scui.rockstargames.com. The overlay is a web page packed in scui.pak in the Social Club folder, and every call it makes is in its script. Read The calls are authorised with the ROS ticket itself, as Authorization: SCAUTH val="<ticket>", plus X-Title-Name: gta5, so like every ticket they end the account's GTA Online session. Measured

Measured

The new picture was live within two minutes, at prod-avatars.akamaized.net/custom-avatars/n/<cid>.png (128 by 128, and /l/ for 256). The avatar is a fixed square cut from the photo, not its centre. Measured

A photo is uploaded the way the game does it, as ROS user content of type gta5photo: a create that answers with a CDN address and a short-lived upload token, the JPEG sent there, then a publish. Once it's on the account it shows up in GetCustomAvatars and can be set like any selfie. This needs write privilege on the build, like a playlist. Measured

Crew emblems

Emblems are made in the old website's editor (/emblems/new). An emblem is a stack of layers, each one of Rockstar's shapes placed with a position, scale, rotation, colour and so on, on a 512 by 512 canvas. These calls use the website's session, not a ticket, so they don't end a GTA Online session. Read

Measured

The old website's calls carry the page's anti-forgery token like its other calls (Old website). The active emblem's files on the content server change within seconds of the activation, and a new gallery emblem's pictures appear over about a minute. Measured

Every crew has a public folder on the content server, prod.cloud.rockstargames.com/crews/sc/<bucket>/<crew id>/publish/. The bucket is a djb2 hash of the crew id written in decimal, modulo 10,000, padded to four digits. emblem/emblem_<size>.png is the active emblem in 32, 64, 128, 256 and 512, and emblem_128.dds is the texture the game asks for. Measured

Old website

• Pages under socialclub.rockstargames.com/games/gtav/<platform>/. Calls are the site's own routes, with the browser's cookies and, for most of them, the anti-forgery token each page carries (__RequestVerificationToken, sent back as a header).
• The platform is session state: calls take no platform parameter and answer for the platform of the last page loaded.
• Career pages: a player's GTA Online statistics per platform, depending on the player's privacy settings.

Playlist search, the one the website still uses: Measured

GET /games/gtav/playlists/ajax/search?SearchOptSort=Played&SearchOptPublisher=&SearchOptDate=&TextQuery=stunt&page=1

Each job in a result carries the same mission block as the job details, and meta.loc. The new API's playlist search does more: one player, any date range, and no account needed.

Glossary

scapi

scapi.rockstargames.com, the API behind the Social Club website

ROS

Rockstar Online Services, the game's back end (*.ros.rockstargames.com)

scui

The in-game Social Club overlay and its API

rsso

The website sign-in's session cookie

BearerToken

The website API's five-minute token

ScAuthToken

The launcher sign-in's token, which mints ROS tickets

Ticket

A ROS session: one day, one per account

UGC

User-generated content: jobs, playlists, photos

Content id

A job's id, shared by the website, playlists and the content server

Rockstar ID

An account's number

pc / pcalt

Website names of Legacy and Enhanced

pcros / pcrosalt

ROS names of Legacy and Enhanced

meta.loc

The map zones a job is filed under, written by the game when it's published

joaat

The game's string hash (Jenkins one-at-a-time, lower-cased input)

Discriminator

Session value that must match for players to meet

X-AMC

"Allow mature content" header, sent by the website when signed out

If you find something wrong here, tell me on the Discord server.