Authentication Tokens

Screeps doesn't have a documented public Web API. However, if you want to use undocumented HTTP endpoints which our server uses to communicate with the client, that's fine. We've developed an authentication tokens system to make this process easier for you.

The regular web browser client uses Google Invisible reCAPTCHA to validate some requests in the background, including the sign-in request. The Steam client uses an encrypted local Steam connection for similar purpose. If you're building some external tool that doesn't require human interaction, you can generate a persistent auth token to make requests without solving CAPTCHA. Such token is generated once and doesn't have expiration time.

Using Auth Tokens

You can generate an auth token in your account settings:

A token with full access will have the same access scope as your usual authentication credentials. You can also limit the access scope to selected endpoints, websockets events and memory segments.

There are two identically valid ways to use this token:

  • Set X-Token header in your request:

     X-Token: 3bdd1da7-3002-4aaa-be91-330562f54093
  • Add _token query param to the URL:

Rate Limiting

Regular requests made by browser or Steam client are NOT rate limited.

However, all requests authenticated by auth tokens are subject to rate limiting rules. When rate capacity is exceeded, you will get 429 HTTP code in response:

HTTP/1.1 429 Too Many Requests

Rate limit exceeded, retry after 51243ms

Three HTTP header are set for informational purposes which you can use to handle rate limiting on your side:

Header Name Description
X-RateLimit-Limit The maximum number of requests you're permitted to make per limit window.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 35
X-RateLimit-Reset: 1514539728

There are two levels of rate limiting: global and per-endpoint, shown in the table below:

Endpoint Rate
Global 120 / minute
GET /api/game/room-terrain 360 / hour
POST /api/game/map-stats 60 / hour
GET /api/user/code 60 / hour
POST /api/user/code 240 / day
POST /api/user/set-active-branch 240 / day
GET /api/user/memory 1440 / day
POST /api/user/memory 240 / day
GET /api/user/memory-segment 360 / hour
POST /api/user/memory-segment 60 / hour
POST /api/user/console 360 / hour
GET /api/game/market/orders-index 60 / hour
GET /api/game/market/orders 60 / hour
GET /api/game/market/my-orders 60 / hour
GET /api/game/market/stats 60 / hour
GET /api/game/user/money-history 60 / hour

Turning rate limiting off

If you develop a third-party tool that requires human interaction, you can integrate a special flow to turn off rate limiting on a specific token. In order to do so, you must provide the user with a link!/account/auth-tokens/noratelimit?token=XXX, which they should navigate to. When the user clicks the "Proceed" button on the page, the token will be granted with a 2-hour period with no rate limits.

If your tool is web-based, you can embed this page in an <iframe> and listen to a screepsTokenSuccess message:

window.addEventListener('message', (event) => {
    if( === 'screepsTokenSuccess') {
        console.log("We are not rate limited now!");
}, false);

Please note that this page uses Google Invisible reCAPTCHA, so that it cannot be used automatically.

You can query info on a specific token (including its unlimited period timer) using the endpoint