Home docs wiiu NNID Server
Post

NNID Server

The account server always responds with an XML body. GET requests are form-encoded. POST and PUT requests have an XML body.

The XML-encoding is not consistent between URLs. Usually, the response contains no XML declaration and no whitespace. However, sometimes the response starts with <?xml version="1.0" encoding="UTF-8" standalone="yes"?>, and sometimes the response is prettified using 4 spaces as indentation.

The common client certificate is needed to connect to these servers.

Main server: https://account.nintendo.net

Other servers:

  • https://game-dev.account.nintendo.net
  • https://system-dev.account.nintendo.net
  • https://library-dev.account.nintendo.net
  • https://staging.account.nintendo.net

Headers

The following headers are included in requests by the Wii U:

FieldDescription
X-Nintendo-Platform-IDAlways 1
X-Nintendo-Device-Type1=Debug, 2=Retail
X-Nintendo-Device-IDUnsigned integer (MCP_GetDeviceId)
X-Nintendo-Serial-NumberString
X-Nintendo-System-VersionVersion of version.bin title (%04X)
X-Nintendo-Region1=JPN, 2=USA, 4=EUR, 8=AUS, 16=CHN, 32=KOR, 64=TWN
X-Nintendo-CountryJP for Japan, DE for Germany, etc.
X-Nintendo-Client-IDa2efa818a34fa16b8afbc8a74eba3eda
X-Nintendo-Client-Secretc91cdb5658bd4954ade78533a339cf9a
X-Nintendo-FPD-VersionAlways “0000”?
X-Nintendo-EnvironmentLx/Dx/Sx/Tx/Jx (default: L1)
X-Nintendo-Title-IDExample: 0005000010138300
X-Nintendo-Unique-IDPart of title id, example: 01383
X-Nintendo-Application-VersionTitle version
X-Nintendo-Device-CertDevice certificate

The server replies with the following headers, in addition to Content-Type (if applicable), Content-Length and Date:

HeaderDescription
X-Nintendo-DateServer timestamp (in milliseconds)
ServerNintendo 3DS (http)

Methods

The following methods can be used without authorization:

MethodURL
GET/v1/api/admin/time
GET/v1/api/admin/mapped_ids
GET/v1/api/content/agreements/Nintendo-Network-EULA/<country>/@latest
GET/v1/api/content/time_zones/<country>/<language>
DELETE/v1/api/devices/@current
PUT/v1/api/devices/@current/inactivate
POST/v1/api/devices/@current/migrations
DELETE/v1/api/devices/@current/migrations
POST/v1/api/devices/@current/migrations/commit
GET/v1/api/devices/@current/status
GET/v1/api/miis
POST/v1/api/oauth20/access_token/generate
POST/v1/api/people
GET/v1/api/people/<nnid>
POST/v1/api/support/coppa/authorization
PUT/v1/api/support/email_confirmation/<%lu>/<%06u>
GET/v1/api/support/forgotten_password/<%lu>
POST/v1/api/support/parental_approval
GET/v1/api/support/parental_approval/send_email/coppa_code
GET/v1/api/support/resend_confirmation
GET/v1/api/support/send_confirmation/pin
GET/v1/api/support/send_forgotten/pin
POST/v1/support/validate/email

The following methods access your account data and require a Bearer authorization token. This token can be retrieved with /v1/api/oauth20/access_token/generate.

MethodURL
PUT/v1/api/people/@me
DELETE/v1/api/people/@me
POST/v1/api/people/@me/deletion
GET/v1/api/people/@me/devices
DELETE/v1/api/people/@me/devices/@current
POST/v1/api/people/@me/devices/@current/attributes
PUT/v1/api/people/@me/devices/@current/inactive
GET/v1/api/people/@me/emails
PUT/v1/api/people/@me/miis/@primary
GET/v1/api/people/@me/profile
GET/v1/api/provider/nex_token/@me
GET/v1/api/provider/service_token/@me

The following methods require a HashedBasic authorization token.

MethodURL
POST/v1/api/people/@me/agreements
POST/v1/api/people/@me/devices
GET/v1/api/people/@me/devices/owner

GET /v1/api/admin/time

This request does not take an parameters. The response body is empty, and no Content-Type header is returned by the server. The server time can be retrieved from the X-Nintendo-Date header.

GET /v1/api/admin/mapped_ids

Converts between PID and NNID. PIDs starts at 1799999999 and decrement on every new account.

ParamDescription
input_type“pid” or “user_id”
output_type“pid” or “user_id”
inputcomma-separated list

Example response:

1
2
3
4
5
6

<mapped_ids>
  <mapped_id>
    <in_id>Kinnay-WiiU</in_id>
    <out_id>1798037410</out_id>
  </mapped_id>
</mapped_ids>

POST /v1/api/oauth20/access_token/generate

This method generates an access token. The access token can be included in the “Authorization” header, and is needed for all requests that require access to your account data.

There are two ways to request an access token: using NNID and password or password hash, or using a refresh token from an earlier access token request.

The password hash can be calculated using the following method:

1
2

data = struct.pack("<I", pid) + b"\x02\x65\x43\x46" + password.encode("ascii")
hash = hashlib.sha256(data).digest()
FieldDescription
grant_type“password”
user_idNNID
passwordPassword or password hash
password_type (optional)“hash”
FieldDescription
grant_type“refresh_token”
refresh_tokenRefresh token

Example response:

1
2
3
4
5
6
7

<OAuth20>
  <access_token>
    <token>...</token>
    <refresh_token>...</refresh_token>
    <expires_in>3600</expires_in>
  </access_token>
</OAuth20>

GET /v1/api/provider/nex_token/@me

Provides login information and location of game server.

ParamDescription
game_server_idGame server id

Example response:

1
2
3
4
5
6
7

<nex_token>
  <host>34.208.166.202</host>
  <nex_password>...</nex_password>
  <pid>1798037410</pid>
  <port>43220</port>
  <token>...</token>
</nex_token>

Errors

Here’s an example error response:

1
2
3
4
5
6
7

<errors>
  <error>
    <cause>client_id</cause>
    <code>0004</code>
    <message>API application invalid or incorrect application credentials</message>
  </error>
</errors>

Sometimes, the cause tag is closed immediately (<cause/>). Sometimes, it is omitted entirely.

Known Errors

CodeCauseMessage
0002 deviceId format is invalid
0002 serialNumber format is invalid
0002 platformId format is invalid
0002 version format is invalid
0002user_iduser_id format is invalid
0002passwordpassword format is invalid
0002X-Nintendo-RegionX-Nintendo-Region format is invalid
0004grant_typeInvalid Grant Type
0004client_idAPI application invalid or incorrect application credentials
0005access_tokenInvalid access token
0007Forbidden request 
0008 Not Found
0100 Account ID already exists
0103emailEmail format is invalid
0106 Invalid account ID or password
0107 Account country and device country do not match
0110 Unlinked device
0113 Unauthorized device
0113device_idUnauthorized device
0118 Unique ID and Game Server ID are not linked
0123 Service has expired
0124 Application version is older than usable version registered
1017 The requested game environment wasn’t found for the given game server.
1022client_idThe requested client was not found.
1033 Excessive forgot password e-mail attempt
1126 The domain “…” is not accessible.
1600Bad RequestUnable to process request
1600Unsupported Media TypeUnable to process request
CodeDescription
1BAD_FORMAT_PARAMETER
2BAD_FORMAT_REQUEST
3REQUEST_PARAMETER_MISSING
4UNAUTHORIZED_CLIENT
5INVALID_ACCOUNT_TOKEN
6ACCOUNT_TOKEN_EXPIRED
7REQUEST_FORBIDDEN
8REQUEST_NOT_FOUND
9WRONG_HTTP_METHOD
10INVALID_PLATFORM_ID
11SYSTEM_UPDATE_REQUIRED
12BANNED_DEVICE_ALL
100ACCOUNT_ID_ALREADY_EXISTS
101ACCOUNT_ID_NOT_ACCEPTABLE
103MAIL_ADDRESS_NOT_ACCEPTABLE
104UNAUTHORIZED_DEVICE
105REACHED_REGISTRATION_LIMIT
106WRONG_ACCOUNT_PASSWORD
107COUNTRY_MISMATCH
108BANNED_ACCOUNT_ALL
110DEVICE_MISMATCH
111ACCOUNT_ID_CHANGED
112ACCOUNT_ALREADY_DELETED
114COPPA_NOT_ACCEPTED
115REACHED_ASSOCIATION_LIMIT
116WRONG_CONFIRMATION_CODE
117CONFIRMATION_CODE_EXPIRED
118GAME_SERVER_ID_UNIQUE_ID_NOT_LINKED
119BANNED_ACCOUNT_IN_APPLICATION
120BANNED_DEVICE_IN_APPLICATION
121BANNED_ACCOUNT_IN_NEX_SERVICE
122BANNED_DEVICE_IN_NEX_SERVICE
123SERVICE_CLOSED
124APPLICATION_UPDATE_REQUIRED
125CLIENT_ID_UNIQUE_ID_NOT_LINKED
126BANNED_ACCOUNT_IN_INDEPENDENT_SERVICE
127BANNED_DEVICE_IN_INDEPENDENT_SERVICE
128MAIL_ADDRESS_NOT_VALIDATED
129WRONG_BIRTH_DATE_OR_MAIL_ADDRESS
130PID_NOT_FOUND
131WRONG_ACCOUNT_MAIL
132BANNED_ACCOUNT_ALL_TEMPORARILY
134BANNED_ACCOUNT_IN_APPLICATION_TEMPORARILY
136BANNED_ACCOUNT_IN_NEX_SERVICE_TEMPORARILY
137BANNED_DEVICE_IN_NEX_SERVICE_TEMPORARILY
138BANNED_ACCOUNT_IN_INDEPENDENT_SERVICE_TEMPORARILY
139BANNED_DEVICE_IN_INDEPENDENT_SERVICE_TEMPORARILY
142COPPA_AGREEMENT_CANCELED
143DEVICE_INACTIVE
1004EULA_NOT_ACCEPTED
1006INVALID_UNIQUE_ID
1016NEX_ACCOUNT_NOT_FOUND
1017GAME_SERVER_ID_ENVIRONMENT_NOT_FOUND
1018GENERATE_TOKEN_FAILURE
1019INVALID_NEX_CLIENT_ID
1020INVALID_CLIENT_KEY
1021INVALID_GAME_SERVER_ID
1022INVALID_CLIENT_ID
1023WRONG_MAIL_ADDRESS
1024MASTER_PIN_NOT_FOUND
1025MAIL_TEXT_NOT_FOUND
1031SEND_MAIL_FAILURE
1032DOMAIN_ACCOUNT_ALREADY_EXISTS
1033EXCESSIVE_MAIL_SEND_REQUEST
1035CREDIT_CARD_GENERAL_FAILURE
1036CREDIT_CARD_DATE_EXPIRED
1037CREDIT_CARD_DECLINED
1038INVALID_CREDIT_CARD_NUMBER
1039CREDIT_CARD_NUMBER_WRONG
1040INVALID_CREDIT_CARD_DATE
1041CREDIT_CARD_BLACKLISTED
1042INVALID_CREDIT_CARD_PIN
1043CREDIT_CARD_PIN_WRONG
1044INVALID_LOCATION
1045INVALID_POSTAL_CODE
1046DEVICE_EULA_COUNTRY_MISMATCH
1100INVALID_EULA_COUNTRY
1101INVALID_EULA_COUNTRY_AND_VERSION
1103PARENTAL_CONTROLS_REQUIRED
1104ACCOUNT_ID_FORMAT_INVALID
1105WRONG_ACCOUNT_PASSWORD_OR_MAIL_ADDRESS
1106AUTHENTICATION_LOCKED
1107ACCOUNT_ID_PASSWORD_SAME
1111APPROVAL_ID_NOT_FOUND
1115PENDING_MIGRATION
1125MAIL_ADDRESS_DOMAIN_NAME_NOT_ACCEPTABLE
1126MAIL_ADDRESS_DOMAIN_NAME_NOT_RESOLVED
1200NOT_PROVIDED_COUNTRY
2001INTERNAL_SERVER_ERROR
2002UNDER_MAINTENANCE
2999NINTENDO_NETWORK_CLOSED

Device Certificate

This header is only sent in the requests for:

  • /v1/api/oauth20/access_token/generate
  • /v1/api/people
  • /v1/api/people/@me/agreements
  • /v1/api/people/@me/devices
  • /v1/api/people/@me/devices/owner

The device certificate consists of 384 base64-encoded bytes:

OffsetSizeDescription
0x00x4Signature type:
0x00010002: SHA-1 (debug)
0x00010005: SHA-256 (retail)
0x40x3CSignature
0x400x40Padding
0x800x40Root-CA<%08X>-MS<%08X>
0xC00x4Key type (always 2)
0xC40x40Device id (NG<%08X>)
0x1040x4NG key id
0x1080x78Public key
Contents