├── README.md └── docs ├── api.md ├── end-user-help.md └── public-api-terms.md /README.md: -------------------------------------------------------------------------------- 1 | nxapi znca API server 2 | --- 3 | 4 | This repository contains a server for generating `f` parameters required to authenticate to the Nintendo Switch Online app API. This was previously part of [nxapi](https://gitlab.fancy.org.uk/samuel/nxapi) ([GitHub](https://github.com/samuelthomas2774/nxapi)), a library and command line and Electron app for using Nintendo's smart device app APIs. 5 | 6 | This uses Frida to call the token generation functions in the Nintendo Switch Online app on a rooted Android device. 7 | 8 | ### Public API 9 | 10 | A server running this API is available at https://nxapi-znca-api.fancy.org.uk/api/znca. If you would like to use this please send me a message in the [nxapi Discord server](https://discord.com/invite/4D82rFkXRv). If your project authenticates as the user's Nintendo Account you must explain that their id_token will be sent to a third-party API, and include a link to here. 11 | 12 | Status is available at https://nxapi-status.fancy.org.uk. Usage stats are available at https://grafana.tt.fancy.org.uk/public-dashboards/442f37612eed4c4a829fd7025b07d152. 13 | 14 | Please read the requirements for using the public API in [docs/public-api-terms.md](docs/public-api-terms.md). 15 | 16 | See [docs/api.md](docs/api.md) for API usage details. 17 | -------------------------------------------------------------------------------- /docs/api.md: -------------------------------------------------------------------------------- 1 | API usage 2 | --- 3 | 4 | The server has two endpoints, `/api/znca/f` and `/api/znca/config`, which are compatible with [the imink API](https://github.com/JoneWang/imink/wiki/imink-API-Documentation)'s `/f` and `/config` endpoints. 5 | 6 | ### `/config` 7 | 8 | `/api/znca/config` can be used to check which app versions are available. 9 | 10 | `nso_version` is the latest version supported by the server. 11 | 12 | The `versions` field is not supported by the imink API. `worker_count` is provided for monitoring/debugging and should not be used by clients. 13 | 14 | ```jsonc 15 | { 16 | "versions": [ 17 | { 18 | "platform": "Android", 19 | "name": "com.nintendo.znca", 20 | "version": "2.4.0", 21 | "build": 3467, 22 | "worker_count": 2 23 | }, 24 | { 25 | "platform": "Android", 26 | "name": "com.nintendo.znca", 27 | "version": "2.5.0", 28 | "build": 3828, 29 | "worker_count": 2 30 | } 31 | ], 32 | "nso_version": "2.5.0" 33 | } 34 | ``` 35 | 36 | ### `/f` 37 | 38 | The following data should be sent as JSON to generate an `f` parameter: 39 | 40 | ```ts 41 | interface ZncaApiRequest { 42 | /** 43 | * `"1"` or `1` for Coral (Nintendo Switch Online app) authentication (`Account/Login` and `Account/GetToken`). 44 | * `"2"` or `2` for web service authentication (`Game/GetWebServiceToken`). 45 | */ 46 | hash_method: '1' | '2' | 1 | 2; 47 | /** 48 | * The token used to authenticate to the Coral API: 49 | * The Nintendo Account `id_token` for Coral authentication. 50 | * The Coral access token for web service authentication. 51 | */ 52 | token: string; 53 | /** 54 | * The current timestamp in milliseconds, either as a number or a string. 55 | */ 56 | timestamp?: string | number; 57 | /** 58 | * A random (v4) UUID. 59 | */ 60 | request_id?: string; 61 | /** 62 | * The user's Nintendo Account ID from https://api.accounts.nintendo.com/2.0.0/users/me (`id`). 63 | * 64 | * For Coral authentication (hash method 1) this will be set automatically from the `token` if not provided. 65 | * (Although providing it is recommended.) 66 | * For web service authentication (hash method 2) this must be provided. If it is not provided an empty string 67 | * will be used, which will cause the resulting f token to be rejected if/when Nintendo starts validating this. 68 | */ 69 | na_id?: string; 70 | /** 71 | * The user's Coral user ID from Account/Login or Account/GetToken (`result.user.id`). 72 | * 73 | * Only used for web service authentication (hash method 2). 74 | * 75 | * This will be set automatically from the `token` if not provided. (Providing it is recommended.) 76 | */ 77 | coral_user_id?: string; 78 | } 79 | ``` 80 | 81 | As the server can support multiple versions of the Nintendo Switch Online app (which generate different `f` values), the `X-znca-Platform` and `X-znca-Version` headers should be used to indicate which version the client is using. 82 | 83 | The `X-znca-Client-Version` header is used to check if the client may be incompatible with newer coral versions and should never be set dynamically. It must be hardcoded as the latest version you've tested, even if the `X-znca-Version` header is set dynamically using the `/config` endpoint. From 2.12.0 this header is required. 84 | 85 | > Due to changes to Nintendo's API on [23/08/2022](https://github.com/samuelthomas2774/nxapi/discussions/10#discussioncomment-3464443) the `timestamp` parameter should not be sent. If the `timestamp` or `request_id` parameters are not sent their values will be generated and returned in the response. Note that unlike the imink API and [nsotokengen](https://github.com/clovervidia/nsotokengen), only parameters not included in the request will be included in the response. 86 | > 87 | > From 2.12.0, the `timestamp` and `request_id` parameters cannot be used. 88 | 89 | ```sh 90 | # Make imink-compatible API requests using curl 91 | curl --header "Content-Type: application/json" --header "X-znca-Platform: Android" --header "X-znca-Version: 2.4.0" \ 92 | --data '{"hash_method": "1", "token": "...", "na_id": "0000000000000000"}' "http://[::1]:12345/api/znca/f" 93 | 94 | # Use the znca API server in nxapi 95 | # This should be set when running any nso or web service commands as the access token will be refreshed automatically when it expires 96 | ZNCA_API_URL=http://[::1]:12345/api/znca nxapi nso ... 97 | ``` 98 | 99 | Information about the device and the Nintendo Switch Online app, as well as information on how long the request took to process will be included in the response headers. 100 | 101 | Header | Description 102 | --------------------------------|------------------ 103 | `X-Device-Id` | ADB device ID (IP address and ADB port) of the Android device 104 | `X-Android-Build-Type` | Android build type, e.g. `user` 105 | `X-Android-Release` | Android release/marketing version, e.g. `8.0.0` 106 | `X-Android-Platform-Version` | Android SDK version, e.g. `26` 107 | `X-znca-Platform` | Device platform - always `Android` 108 | `X-znca-Version` | App release/marketing version, e.g. `2.2.0` 109 | `X-znca-Build` | App build/internal version, e.g. `2832` 110 | 111 | The following performance metrics are included in the `Server-Timing` header: 112 | 113 | Name | Description 114 | ------------|------------------ 115 | `validate` | Time validating the request body. 116 | `attach` | Time waiting for the device to become available, start frida-server, start the app and attach the Frida script to the app process. This metric will not be included if the server is already connected to the device. 117 | `queue` | Time waiting for the processing thread to become available. 118 | `init` | Time waiting for `com.nintendo.coral.core.services.voip.Libvoipjni.init`. 119 | `process` | Time waiting for `com.nintendo.coral.core.services.voip.Libvoipjni.genAudioH`/`genAudioH2`. 120 | 121 | ### Health monitoring 122 | 123 | An additional endpoint is available for monitoring service availability. 124 | 125 | When sending a GET request to `/api/znca/health`, the server will attempt to generate an `f` token if one was not successfully generated in the last 30 seconds, and return the timestamp the last `f` token was generated. The same headers as above will be returned, excluding validation time. 126 | 127 | `/api/znca/devices` will return the list of worker devices connected to the server. 128 | 129 | These endpoints are only provided for monitoring/debugging purposes. 130 | -------------------------------------------------------------------------------- /docs/end-user-help.md: -------------------------------------------------------------------------------- 1 | nxapi f-generation API 2 | --- 3 | 4 | nxapi-znca-api is an API used by nxapi and other applications that use the Nintendo Switch Online app's API, including game-specific services such as SplatNet 3 and NookLink, to authenticate to Nintendo's servers. 5 | 6 | The f-generation API generates a value (known as `f`) normally generated by the Nintendo Switch Online app when you sign in with your Nintendo Account. To do this, it needs the Nintendo Account ID token the app uses to authenticate to it's own API (the API that nxapi and other applications use). 7 | 8 | No other information is required by the Nintendo Switch Online app's API for authentication, so it is possible to access the API as your account with only this token. The ID token does not allow full access to your Nintendo Account however, and does not contain your sign-in ID, email address, or password. The token includes the following information: 9 | 10 | - Your Nintendo Account ID 11 | - Your Nintendo Account country 12 | - Information about the token itself, such as when it expires 13 | 14 | When accessing a game-specific service, the API is used to generate another `f` value, using the token the Nintendo Switch Online app uses to access it's API after authenticating using an ID token. This token includes the following information: 15 | 16 | - Your Nintendo Switch Online app user ID 17 | - Your Nintendo Switch Online membership status (either active or inactive) 18 | - Your child restriction status (either 13+ or under 13) 19 | - Information about the token itself, such as when it expires 20 | 21 | This token does not include your Nintendo Account ID so cannot be linked to the first token. 22 | 23 | The f-generation API does not store Nintendo Account ID tokens or Nintendo Switch Online app tokens. The API does store the user identifier, either the Nintendo Account ID or the Nintendo Switch Online app user ID depending on the type of request, to prevent excessive and unnecessary requests from a single user, either due to malicious or misbehaving clients, as this would prevent other users from using the service. The API also stores request logs which include your network address and the User-Agent sent by the software used, which may contain limited information about your system. 24 | 25 | The f-generation API is developed and run by [@samuelthomas2774](https://github.com/samuelthomas2774). I do not maintain any software that uses this API other than nxapi; please contact the maintainers of the software you are using if you have any issues. 26 | -------------------------------------------------------------------------------- /docs/public-api-terms.md: -------------------------------------------------------------------------------- 1 | ### Requirements for developing clients using the public API 2 | 3 | - The `X-znca-Platform` and `X-znca-Version` headers *should* be sent, and may use the config endpoint to retrieve the latest version 4 | - The `X-znca-Client-Version` header *must* be sent and *must not* be set dynamically 5 | - The `timestamp` and `request_id` fields *should not* be sent (from 2.12.0, these will not work) 6 | - The `User-Agent` header *must* be sent and *must* contain your project's name and version, and contact details 7 | - The preferred format is `project/version (+url)`, e.g. `nxapi/1.0.0 (+https://github.com/samuelthomas2774/nxapi)`; libraries that use the API should include a User-Agent component for both the library and the dependent software, e.g. `library/1.0.0 (...) nxapi/1.0.0 (...)` 8 | - The client *should* attempt to imitate Nintendo's official apps as closely as possible 9 | - Where the below requirements include informing the user that account tokens are sent to any non-Nintendo service, including this API and the service itself, the client/service *must* do so *before* asking the user to sign in using their Nintendo Account, and *must* require the user to explicitly acknowledge this before contacting non-Nintendo services 10 | - You may want to include a link to [docs/end-user-help.md](./end-user-help.md) 11 | - The client *must* cache tokens for their full validity period, unless deletion is requested, or access is no longer required, and *must* only renew tokens as Nintendo's official apps/web services do 12 | 13 | For clients that authenticate using a user's account: 14 | 15 | - The client *must* inform the user that their Nintendo Account id_token (and, if applicable, coral token) will be sent to a third-party API 16 | - The client *must* include a link to this project 17 | 18 | For services that authenticate using a user's account via another server: 19 | 20 | - The service *must* inform the user that their Nintendo Account session token will be sent to/stored by your service 21 | - The service *may* use the authorisation code grant, without requesting the `offline` scope, instead of Nintendo's custom session token code grant as normally used by the Nintendo Switch Online app, when only temporary access to the user's account is required 22 | - The service *must* suitably encrypt stored Nintendo Account session tokens, and *must not* allow retrieval of session tokens 23 | - The service *must not* allow anyone other than the user who provided the session token/session token code/similar long-term token to cause the service to perform requests to Nintendo services using that user's account, including by administrators (this does not mean that you can't share data retrieved by that user with other users or services) 24 | - The service *must* provide an option to allow users to delete their Nintendo Account session tokens/similar provided tokens, and any cached tokens, and cease sending any requests to Nintendo services using their account immediately on request 25 | - The service *must* only perform requests to Nintendo services using a user's account in response to the user interacting with the service 26 | - The service *may* make automated requests to Nintendo services using a user's account, at a limited frequency, only if the user has explicitly allowed this, and has recently interacted with the service 27 | - The service *must* limit requests to this API to 1 concurrent request for users that are not interacting with the service (that means, when handling interactions for multiple users, multiple simultaneous requests can be sent, but only one automated request) 28 | - The service *must* appropriately handle errors, such as by deleting a user's session token if an `invalid_grant` error is received 29 | - The service *must not* automatically retry requests to this API, except for network errors where the connection is closed before a HTTP response is received, or as specified by the `Retry-After` header 30 | - The service *must not* automatically retry requests to Nintendo services, except for network errors where the connection is closed before a HTTP response is received 31 | --------------------------------------------------------------------------------