Authentication and server keys
The blocking API authenticates with a single server key. There are three ways to get one, and the way you choose decides whether the key is bound to an IP and how long a block can last. The read API needs no authentication.
Kinds of keys
| Format | Name | Where it goes | Lifetime |
|---|---|---|---|
| slsrv_… | Server key | Authorization header of every report | Until revoked |
| slclm_… | Discord code | Body of POST /api/plugin/v1/claim. Exchanged for a server key | 24 hours after issue, single use |
A server key is returned exactly once, in the response that issues it. We store only a hash, so a lost key cannot be looked up. Issue a new one.
Header format
Authorization: Bearer slsrv_Kd82mQ1xPz…
Write Bearer, one space, then the key. Bearer is case-insensitive. A missing or wrong key answers 401 {"error":"invalid credential"}. A revoked key and a report sent from an IP other than the registered one get the same 401; the response does not say which.
The three ways to get a key
| Self-claim | Discord + plugin | Discord HTTP key | |
|---|---|---|---|
| How it is issued | POST /api/v1/servers/claim | POST /api/plugin/v1/claim | A button on the Discord code panel |
| Proof of ownership | An SCP:SL server answers A2S_INFO at the request IP:port | A Discord account plus a code sent from the game server | A Discord account |
| Reports accepted from | The registered IP | The registered IP | Anywhere |
| Longest block per seed | 1 hour | 1 hour | 20 minutes |
| Issue limits | 1 per IP every 5 min, 3 live keys per IP | Servers per account (default 1) | Servers per account (default 1) |
| Report endpoint | POST /api/v1/servers/report | POST /api/plugin/v1/report | POST /api/v1/servers/report |
| Revocation | POST /api/v1/servers/revoke, or claim the same IP:port again | POST /api/v1/servers/revoke, the Discord panel, or claim the same address again | POST /api/v1/servers/revoke or the Discord panel |
If you write your own client, use self-claim. Use an HTTP key only when you cannot send requests from the game server machine. An HTTP key is not proven to come from a real server, which is why its block cap is a short 20 minutes.
How the request IP is decided
The request IP is the CF-Connecting-IP header set by the CDN. No request field carries an IP. IPv6 addresses are compared by value, ignoring notation. Self-claim and plugin keys are bound to that IP; a report from any other IP gets 401.
Replacement and revocation
- When a new key is issued for the same IP:port, the previous key is revoked. Reports with it get 401.
- Whoever holds a key can revoke it at any time with POST /api/v1/servers/revoke. A server registered through Discord can also be revoked from the Discord panel. Reports with a revoked key get 401.
- Revocation is immediate and cannot be undone. Issue a new key.
- Stop reporting when you get 401. Resending with the same key gives the same answer.
Keeping the key
- Keep the key in a config file or secret store. Never paste it into logs, chat or a source repository.
- An HTTP key is not bound to an IP: anyone who has it can block seeds in your server's name for 20 minutes at a time. If it leaks, send POST /api/v1/servers/revoke with that key right away and get a new one.
- Request records keep only the first 12 characters of a key. That prefix is all you need to quote when asking for help.