Skip to content

api docs

Jump to bottom
eli edited this page May 25, 2023 · 30 revisions

This API is now offline.

Generation of f tokens is now done via the imink API (privacy policy).

Alternatively, use one of these tools to generate tokens locally without calls to a third-party API.

No calls need to be made to the s2s API (at elifessler.com) or flapg API (at flapg.com) in order to successfully use the splatnet2statink script.

☆★ The splatnet2statink API was deprecated since s2s v1.8.0 (released August 2022) and remained online through the end of the year due to its use by various users & tools (Salmonia, NSO-RPC, Splatoon2StreamingWidget, older versions of nxapi and s2s, among others). In January 2023, the s2s API endpoint was taken offline.

THE INFORMATION BELOW IS OUTDATED & PRESERVED HERE FOR ARCHIVAL PURPOSES ONLY.

splatnet2statink API documentation

Update – February 2019: This API's function has changed and no longer generates f tokens directly; it must now be used in conjunction with the flapg API (described below). Please note the URL change from /gen to /gen2.

POST https://elifessler.com/s2s/api/gen2 (DEPRECATED)

  • Request:
    • Content-Type: application/x-www-form-urlencoded
    • User-Agent: user_agent/version.num
    • Body: {"naIdToken": "your_token", "timestamp": "unixtime"}
  • Response: A Base64 hash value.
    • Content-Type: application/json

Examples

>>> import requests, time
>>> now = int(time.time())
>>> r = requests.post("https://elifessler.com/s2s/api/gen2",
          headers={'User-Agent': "myAppName/0.1"},
          data={'naIdToken': "your_token", 'timestamp': now})

$ curl -X POST -d "naIdToken=your_token&timestamp=unixtime" https://elifessler.com/s2s/api/gen2

How it works

Sending a POST request to the splatnet2statink API computes a unique hash using two pieces of information: a Unix epoch timestamp and a user's id_token.

This hash can then be passed to the flapg API (an Android server emulating the Nintendo Switch Online Android app) – along with that same id_token, timestamp, and a UUID – to create a unique HMAC (keyed-hash message authentication code). This is done within Nintendo's app in an obfuscated manner.

The goal of these combined API requests is to ultimately return a value f that can be sent to Nintendo to generate an iksm_session cookie, which is used to access SplatNet information (e.g. stage rotation, shop, user battles) or view SplatNet from a web browser.

Note: Due to NSO app updates in April 2019 (v1.5.0 of the script) and again in March 2020 (v.1.5.4), the below flowchart is slightly outdated. The flapg API must be called twice, in two separate steps, and now returns multiple tokens that are used to further authenticate with Nintendo at a second, later point in the process.

flowchart

  • An iksm_session cookie can be generated only by Nintendo via an f token.
  • An f token can be generated by Nintendo's app given a hash value and a user's id_token (this is the flapg API's purpose).
  • A valid hash value can be generated by anyone based on their id_token (this is the s2s API's purpose).
  • A user's id_token can be generated only by Nintendo based on their session_token.
  • A user's session_token can be generated only by Nintendo given their username (NNID/email), password, and manual confirmation (button press on the website).

As shown and described above, making a valid request to the splatnet2statink API (and flapg API) entails sending your id_token to the API – however, no other information, including session_token, username, or password, is sent. Usernames and passwords are far removed from where the API comes into play and are never readable by anyone but you. You can verify this by viewing the source code of iksm.py.

For more information, see https://github.com/ZekeSnider/NintendoSwitchRESTAPI.

The flapg API

The splatnet2statink API must be used in conjunction with @NexusMine's flapg API in order to generate f tokens. Please reach out for prior approval.

GET https://flapg.com/ika2/api/login?public

  • Headers:
    • x-token: Your id_token
    • x-time: Unix epoch timestamp
    • x-guid: Any UUID
    • x-hash: The hash value returned by the s2s API
    • x-ver: 3
    • x-iid: "nso" or "app"
  • Response: Various tokens for authentication (including f, within the result object).
    • Content-Type: application/json

The timestamp and UUID headers must be the same as those used in previous requests to Nintendo servers.

Privacy & security

The splatnet2statink API is hosted on my website, elifessler.com. Your connection to elifessler.com and the s2s API is secure and performed solely over HTTPS.

To prevent abuse, API requests will be logged and stored with the following information:

  • IP address – the IP address of the user who made the request
  • Time – the time and date the request was made
  • User agent – the user agent (and version) of the client that made the request
  • Response – the HTTP status code and response regarding the success state, out of the following values:
    • 200 (OK): A hash value was returned successfully
    • 400 (Bad Request): Request body was incorrect
    • 403 (Forbidden): Request made was made with an insecure connection or disallowed user agent
    • 405 (Method Not Allowed): A method other than POST was attempted
    • 429 (Too Many Requests): API has received too many recent requests
    • 503 (Service Unavailable): API is under maintenance

No other data, such as any information about a user's account, a user's id_token (naIdToken), or the returned hash value, is logged or stored. In addition, it is not possible to use either sent or stored data to identify which account/user performed a request, to view any meaningful information about a user, or to gain access to an account.

Rate limits & error messages

Update – July 2022: The limit described below has been increased from 4 to 10 requests allowed per minute.

The splatnet2statink API uses a token bucket system to control traffic. Requests to the API are globally limited to ten per minute. If you receive an error, please wait ~30 seconds before trying again.

If using splatnet2statink to access the API, please use an updated version, or an error will be returned. This prevents bad requests from being sent to Nintendo's servers (who also require the use of an updated version of the NSO app).

Error messages will be of the form {"error": "Error text"}.

Integration and use

If you wish use this API in your app or service, you must: 1) contact me to let me know, 2) use a unique and properly-formatted user agent string with version number for all requests, 3) transparently communicate to users that this involves making a request to a non-Nintendo server, and 4) provide an alternative method or workaround in your app, e.g. allow for and provide/link to adequate instruction on how to use mitmproxy to obtain and manually enter the cookie instead.

Your app or service must provided free of charge, and should not ask for donations to unlock features. To avoid unwanted negative attention from Nintendo, we strongly discourage displaying ads to users, which are also a detriment to users' experiences (and are unlikely to make much money, given the niche nature of the service).

Note that, unless you need player-specific data such as a battle record – i.e. if you're just dealing with stuff like stage rotation, the SplatNet Gear Shop, Splatfest info, etc. – the splatoon2.ink API will also serve your purposes while being significantly simpler.

Disclaimer

You use this script and the splatnet2statink API at your own risk. None of the creators or contributors to splatnet2statink are responsible for anything that happens to your account as a result of using this script or making any requests to the API.

Clone this wiki locally