https://github.com/osu-community-tournaments/osu-api-proxy
A proxy for osu! api for tournament spreadsheets
https://github.com/osu-community-tournaments/osu-api-proxy
osu osu-api osu-tournament osu-tourney
Last synced: 5 days ago
JSON representation
A proxy for osu! api for tournament spreadsheets
- Host: GitHub
- URL: https://github.com/osu-community-tournaments/osu-api-proxy
- Owner: osu-community-tournaments
- Created: 2026-05-15T21:48:37.000Z (about 2 months ago)
- Default Branch: master
- Last Pushed: 2026-05-15T23:42:51.000Z (about 2 months ago)
- Last Synced: 2026-05-16T00:53:20.053Z (about 2 months ago)
- Topics: osu, osu-api, osu-tournament, osu-tourney
- Homepage:
- Size: 20.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-osu-tournaments - nginx - nginx config for running a proxy (Community Resources / Google Sheets Templates)
README
# osu! API Proxy (pure nginx)
## What it does
- Forwards `/api/*` and `/oauth/token` to `https://osu.ppy.sh`.
- Rejects everything else with 404.
- Applies `limit_req` rate limiting at 3 r/s (burst 10).
- Optionally requires a shared secret via header or query string.
- Strips Cloudflare-style headers (`CF-Connecting-IP`, `CF-Ray`, …) before
forwarding upstream.
## Prerequisites
- A Linux VPS with nginx (≥ 1.18 — anything modern).
- A TLS cert for the chosen domain (Let's Encrypt / certbot / acme.sh / etc.).
## Deploy
There are two flavors of the server block. Pick one.
| File | When to use |
|-------------------------------|------------------------------------------------------------------|
| `nginx.conf.example` | Open proxy. Network-level access control (firewall, private DNS). |
| `nginx-secret.conf.example` | Anyone can hit the domain; require a shared secret. |
### Steps
1. **Copy configuration with your details** into `/etc/nginx/sites-available/osu-proxy.conf`.
Adjust `server_name` and `ssl_certificate*` to your domain.
2. **Enable & reload:**
```bash
ln -s /etc/nginx/sites-available/osu-proxy.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
```
3. **Verify:** `curl https://your.domain/health` → `{"status":"ok",...}`.
## Authentication (secret variant)
Send the secret in one of:
| Method | Example |
|-----------------------|------------------------------------------------------------------------|
| Header (recommended) | `X-Proxy-Secret: your-secret-here` |
| Query param (API v2) | `https://your.domain/api/v2/...?proxy_secret=your-secret` |
| Query param (API v1) | `https://your.domain/api/get_beatmaps?k=KEY&proxy_secret=your-secret` |
The `proxy_secret` query parameter is stripped before the request is
forwarded to osu.ppy.sh. The `X-Proxy-Secret` header is also stripped.
The secret lives in your nginx config. Keep that file readable only by
nginx (`chmod 0640`, owned by root, group nginx).
## Apps Script usage
Replace all `https://osu.ppy.sh` with your proxy URL. If you use the secret
variant, add the header to every `UrlFetchApp` call:
```js
var options = {
method: "get",
headers: {
"Authorization": "Bearer " + osuToken,
"X-Proxy-Secret": "your-secret-here"
}
};
var response = UrlFetchApp.fetch(url, options);
```