Skip to content

api docs

Jump to bottom
eli fessler edited this page Sep 24, 2018 · 30 revisions

The API is currently under maintenance as the f generation method has changed. See here for more information.

splatnet2statink API documentation

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

  • Request:
    • Content-Type: application/x-www-form-urlencoded
    • User-Agent: user_agent/version.num
    • Body: {"naIdToken": "your_token"}
  • Response: An f token.
    • Content-Type: application/json

Examples

>>> import requests
>>> r = requests.post("https://elifessler.com/s2s/api/gen",
         headers={'User-Agent': "user_agent/version.num"},
         data={'naIdToken': "your_token"})

$ curl -X POST -d "naIdToken=your_token" https://elifessler.com/s2s/api/gen

How it works

Sending a POST request to the API computes a unique HMAC (keyed-hash message authentication code) using three pieces of information: the key (stored securely in the API), a cryptographic hash function, and a user's id_token.

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

flowchart

  • An iksm_session cookie can be generated only by Nintendo via an f token.
  • An f token can be generated by anyone, given the key and a user's id_token (this is the 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 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.

Privacy & security

The API is hosted on my website, elifessler.com. Your connection to elifessler.com and the splatnet2statink 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): if an f token (valid or not) was returned successfully
    • 400 (Bad Request): if the request body was incorrect
    • 403 (Forbidden): if a request made was made with an insecure connection or disallowed user agent
    • 405 (Method Not Allowed): if a method other than POST was attempted
    • 429 (Too Many Requests): if the API has received too many recent requests
    • 503 (Service Unavailable): if the 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 f 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 at 2 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