Skip to content

api docs

Jump to bottom
eli fessler edited this page Apr 7, 2018 · 30 revisions

splatnet2statink API documentation

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

  • Request body: The key naIdToken and a corresponding value in JSON format: 
    { "naIdToken": "..." }
  • Response: An f token. (Content-Type: application/json)

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 for ~60 days 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 of the client that made the request (e.g. splatnet2statink + version number)
  • 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

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.

Integration and use

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

Disclaimer

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

Clone this wiki locally