Modbot Docs
API

VRChat proxy

Send requests to VRChat's own API through your Modbot, as the group's service account or with your own VRChat session, without handing anyone the account's password.

The VRChat proxy forwards a request to VRChat's API and answers with whatever VRChat said. A script, a tool or a VRChat client library points at your Modbot instead of at api.vrchat.cloud, signs in with a Modbot API key, and the request goes out as the group's service account, on the same session and the same pacing Modbot uses for itself. Nobody needs the account's password.

The proxy is off until an administrator turns it on under Settings → VRChat proxy.

The second switch on that tab, Proxy VRChat images through Modbot, is a different thing and is on by default. See VRChat pictures.

The address

https://modbot.example.com/api/proxy/vrchat/ followed by the VRChat path, exactly as it appears under https://api.vrchat.cloud/:

You wantSend
GET https://api.vrchat.cloud/api/1/users/usr_…GET https://modbot.example.com/api/proxy/vrchat/api/1/users/usr_…
POST https://api.vrchat.cloud/api/1/groups/grp_…/bansPOST https://modbot.example.com/api/proxy/vrchat/api/1/groups/grp_…/bans

The address is shown on the VRChat proxy tab as Address, with a copy button. GET, POST, PUT and DELETE are forwarded; the query string and a JSON body go with them.

Signing in

There are three ways a request can be signed in, and Modbot looks for them in this order.

A Modbot API key in the header

curl -H "Authorization: Bearer mbk_..." \
  https://modbot.example.com/api/proxy/vrchat/api/1/users/usr_...

The request goes out as the service account. The key needs the Use the VRChat proxy permission (see roles and permissions).

VRChat's own API reads its session from a cookie called auth, and every VRChat client library sends whatever it was given as that cookie. So a library can be given a Modbot key where it expects a VRChat session:

curl -b "auth=mbk_..." https://modbot.example.com/api/proxy/vrchat/api/1/users/usr_...

Modbot recognises the key by its mbk_ start and treats it exactly as a key in the header: the same permission, the same limits, the same last-used time. Point a library's base address at your proxy, give it the key as its auth cookie, and it works as the service account.

Your own VRChat session

Anything else in the auth cookie is taken to be your own VRChat session, and the request goes out with your cookies and nothing of Modbot's:

curl -b "auth=authcookie_..." https://modbot.example.com/api/proxy/vrchat/api/1/auth/user

Modbot does not read, store or log the cookie; it forwards it. This needs no Modbot key and no Modbot account. It exists so a tool that already has a VRChat session can go through the same address and the same outgoing proxy (Outgoing address) as everything else, which matters on a host whose own network VRChat blocks.

Nothing

A request with no key and no auth cookie is answered 401.

What is and is not forwarded

Only what an API call needs to say reaches VRChat: the method, the path, the query string, the body and its content type, and the Accept, Accept-Language, If-None-Match and If-Modified-Since headers. Everything else is dropped. In particular:

  • Your Authorization header never goes to VRChat: it is your Modbot key.
  • On the service account, your Cookie header never goes to VRChat either. The session comes from Modbot's own store.
  • The User-Agent is always Modbot's, naming the operator, as on every request Modbot sends.

On the way back you get VRChat's status code and body as they were, with Content-Type, ETag, Last-Modified, Cache-Control, Retry-After and Cloudflare's CF-Ray. On the service account a Set-Cookie from VRChat is kept by Modbot and never returned: it is the service account's session. With your own cookie, a Set-Cookie is yours and comes back.

The answer also carries X-Modbot-Proxy-Account: service or own, so a tool can tell which account it was.

Pacing

Every proxied request goes through Modbot's rate limiter, on a budget of its own that never queues in front of the member sweeps, the audit log or a moderator's ban:

AccountBudgetCounted against the account-wide ceiling
Service accountOne request every three secondsYes
Your own cookieOne request every two secondsNo: it is a different account

When VRChat answers 429 to a proxied request, Modbot stops that budget for a while and never retries, the same way it treats a rate limit anywhere else. Until it opens again, requests are answered 429 by Modbot itself with an error saying so, and the Health page shows the proxy row under VRChat request limits as stopped.

The proxy is for trying an endpoint and for one-off scripts. Modbot cannot tell which VRChat endpoint a forwarded request reaches, so a script that reads the member list through the proxy is spending the proxy's budget beside the sweep that already reads it, and a rate limit it earns is recorded on the proxy rather than on the sweep. Anything that needs the whole list has the API for that.

Answers from Modbot itself

StatusMeaning
404 { "error": "The VRChat proxy is off." }Turn it on under Settings → VRChat proxy.
401No key, no session and no VRChat cookie, or a key Modbot does not accept.
403The key or account lacks Use the VRChat proxy, or the account has not linked its VRChat account.
413The body is larger than 1 MB.
429Modbot's own pacing has stopped the proxy after a rate limit from VRChat.
503Modbot has no VRChat session to use, is waiting to sign in, or could not reach VRChat. The error sentence says which.

Any other status is VRChat's own, passed through.

The playground

Settings → VRChat proxy has a Playground: pick a method, type a path, add a body for a POST or PUT, and press Send. For POST, PUT or DELETE, which can change or delete things on VRChat as Modbot's own account, Send turns into a red Send POST, Send PUT or Send DELETE to confirm. Pressing Enter in the path field only ever sends a GET. The request goes through the proxy as you, signed in to the web app, with the same permission a key needs, and the answer is shown with its status and its body.

Where to next

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page