Intro to Nintendo Switch REST API

6 min readNov 24, 2020

Animal Crossing New Horizons — a popular Nintendo Switch game

Thanks to community effort, we can programmatically access Nintendo Switch App’s API at zero cost. This allows us to build apps capable of communicating with games connected to Nintendo Switch Online (NSO), as well as getting user information like games played and playtime.

*Type messages or use reactions in Animal Crossing with API requests!*

Accessing the API

Getting Nintendo Session Token from Nintendo’s Website
Getting Web Service Token
Using Web Service Token to get game-specific session cookies
Access API through session cookies

1. Nintendo Session Token

When someone logins to Nintendo’s special authorization link, Nintendo redirects the browser to a url containing the session token.

To generate this link, we need to include a S256 code challenge in base64url format. No need to worry if you don’t know what this means right now. Put simply, we are handing over the hashed value of our key to Nintendo, and later we will use the original key as proof we are the same person who logged in.

$ npm install base64url, request-promise-native, uuid

Beginner’s Tip: type the following commands to quickly run JavaScript on your Terminal:
$touch myApp.js to create the file.
$nano myApp.js to modify the contents.
$node myApp.js to run the program.

You should get a URL similar to this:
https://accounts.nintendo.com/connect/1.0.0/authorize?state=[SessionStateReturnedHere]&redirect_uri=npf71b963c1b7b6d119://auth...

Visit the URL on your browser and login to your Nintendo Account. You will be directed to this page.

ight click on the Select this account button and copy the redirect link. It will be in this format:

npf71b963c1b7b6d119://auth#session_state=[SessionStateReturned]&session_token_code=[SessionTokenCodeReturned]&state=[StateReturned]

Instead of the usual HTTP or HTTPS protocol, the returned link’s protocol is npf71b963c1b7b6d119, which is why you can’t simply click and have the browser redirect you.

To build an app for this, we can either have the user right click -> copy and tell us their redirect url, or we could subscribe to the npf protocol and automatically redirect the user back to our app.

We can then extract the Session Token Code from this redirect url.

const params = {};
redirectURL.split('#')[1]
        .split('&')
        .forEach(str => {
          const splitStr = str.split('=');
          params[splitStr[0]] = splitStr[1];
        });
// the sessionTokenCode is params.session_token_code

With the Session Token Code, we can make a request to Nintendo to obtain the Nintendo Session Token.

At the time of this writing, the NSO app version is 1.9.0, which changes around 1~2 times a year. Check this repo for updates.

2. Web Service Token

Here are the steps to get the Web Service Token:

I. Get API Token with Session Token
II. Get userInfo with API Token
III. Get the f Flag [NSO]
IV. Get the API Access Token with f Flag [NSO] and userInfo
V. Get the f Flag [App] with API Access Token
VI. Get Web Service Token with API Access Token and f Flag [App]

This may look daunting, but in implementation is simply a sequence of async server requests.

Now implement those requests.

Call the functions to get our Web Service Token.

This is what the returned Web Service Token looks like.

Congratulations for making it this far! Now the fun with Nintendo API begins :)

Accessing SplatNet for Splatoon 2

To access SplatNet (Splatoon 2), we will use the Web Service Token to obtain a cookie called iksm_session.

With this cookie, we can directly visit SplatNet on the browser by modifying the iksm_session cookie.

Beginner’s Tip: To modify cookies on Chrome, press F12 for Developer Tools -> Applications Tab -> Storage. You can edit, add, and remove cookies there.

We can monitor the network tab in Developer tools while browsing SplatNet and see the APIs being called.

Here is the result for running the records API endpoint.

Common SplatNet Endpoints

/results shows the most recent 50 matches.
/coop_results shows the most recent 50 Salmon Run matches.
/schedules shows the coming rotations.
/coop_schedules shows the coming Salmon Run rotations.
/x_power_ranking/201101T00_201201T00/summary shows the current highest X Power on the leaderboard as well as your current X Power.

Accessing Animal Crossing

To access Animal Crossing, we need to first get its Web Service Token.

(async () => {
    const sessionToken = await getSessionToken(params.session_token_code, authParams.codeVerifier);
    const webServiceToken = await getWebServiceTokenWithSessionToken(sessionToken, game='AC');
    const acTokens = await getCookiesForAnimalCrossing(webServiceToken.accessToken);

Once we access the Animal Crossing Endpoint, the Web Service Token will be stored as the _gtoken. We need this cookie to access the User API for another cookie called _park_session as well as an authentication bearer token.

Common Animal Crossing Endpoints

/sd/v1/users shows user’s name, island, passport photo.
/sd/v1/users/:user_id/profile?language=en-US shows the passport of one user.
/sd/v1/lands/:land_id/profile shows island data.
/sd/v1/friends lists best friends and their information.
/sd/v1/messages sends message or reaction in-game with a POST query.

POST request body for sending messages:

{
  "body": "Sweet",
  "type": "keyboard"
}

POST request body for sending reactions:

{
  "body": "Aha",
  "type": "emoticon"
}

List of Reaction Values

Refreshing Tokens & Cookies

Once the Web Service Token has expired, we can obtain a new one with our initial Nintendo Session Token. There is usually no need to login again.

Summary

Nintendo Switch API enables apps to communicate with game and user information.
User authentication is required to get an access token, which can be used to acquire a Web Service Token.
With the Web Service Token, we can generate game-specific cookies to access game API.

Example Projects

Splatnet/Music Bot: A Discord bot that allows users to show their Animal Crossing Passport and their Splatoon 2 ranks.

Squid Tracks: A full-feature desktop client for Splatoon 2. I recently helped update the authentication logic for this app to get it running again.

Splatnet Desktop: A simple electron application I wrote to access SplatNet on desktop with straightforward authentication.

Splatoon2.Ink: Website that shows current Splatoon 2 stages.

Streaming Widget: A widget that shows Splatoon 2 match results.

Make Your Animal Crossing Character React to Your Gestures With Machine Learning

Overview

yui-spl2.medium.com

How To Connect Nightbot To Splatoon 2’s SplatNet

Set up a free python server so Nightbot can tell Twitch chat your SplatNet Information such as your match KDs, ranks…