Skip to content

api docs

Jump to bottom
eli edited this page Apr 2, 2020 · 30 revisions

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.

splatnet2statink API documentation

POST https://elifessler.com/s2s/api/gen2

  • 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
>>> r = requests.post("https://elifessler.com/s2s/api/gen2",
         headers={'User-Agent': "user_agent/version.num"},
         data={'naIdToken': "your_token", 'timestamp': "unixtime"})

$ 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 that as of v1.5.0 of the script, released in April 2019, the below flowchart is slightly outdated. The flapg API 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.

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

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

Error messages returned 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 should also serve your purposes while being a bit 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