Skip to content
N

nxapi-auth

nxapi-auth is a web service that allows you to link and verify your Nintendo Switch user and self-enrol for presence API access. You can sign in using a Discord account or using a passkey or security key.

To do:

  • Authentication
    • Discord
    • Linking additional Discord users
    • WebAuthn
    • WebAuthn credential registration
    • WebAuthn user registration
  • User settings
    • Discord user management
    • WebAuthn credential management
    • Set name/sync Discord name
    • Token management
  • Nintendo Switch user linking
    • Lookup
    • Verification
    • Server token management for user verification
  • Presence server enrolment
    • Assigning presence server user
    • Sending friend request
    • Completion verification
    • Background verification (try to refresh status of pending enrolments to prevent issues when a user removes the presence server user as a friend before completion)
    • Generate presence server URLs
    • Generate presence server URLs with authentication token when presence data is set to private
    • Check presence permissions are set correctly
    • Check play activity permissions are set correctly (when user is online)
  • Nintendo Switch user settings
    • Set presence data permissions
    • Set Splatoon 3 Splatfest voting history permissions
    • Set friend code permissions
    • Set friend code lookup permissions
    • Set Discord lookup permissions
      • wait what's this for again?
    • Set NSA ID lookup permissions for other services
    • Set friend code URL
    • Update Discord users for role connections
    • Creating/deleting public profile page
  • Public profile pages
    • Profile page
    • Set profile information
      • Use Switch user name/icon?
      • Bio
      • Profile links/fields
      • Birthday
      • Location (limit to country?)/timezone
    • Banner image/colour
    • Profile themes, other personalisation options?
    • Set presence/friend code visibility
    • Set Splatfest team visibility
    • Set username
    • Splashcat integration
    • ... other integrations?
  • Presence API
    • Traefik forward auth service for presence API
    • Headers for limited access (e.g. token with presence access but not title/play activity)
    • [nxapi] Use access headers
  • Integration with nxapi Electron app
    • API to link users with web service token NSA assertion from nxapi-znca-api, obtained when decrypting Game/GetWebServiceToken responses
    • URI scheme to set up presence from web app
    • Fetch friends public profile information
  • API for third-party apps
    • OAuth client management (mostly done, no UI for JWKS URIs/client secrets)
    • User app settings/authorisation management
      • List authorised/previously authorised apps/apps with active sessions
      • Set per-app permissions, e.g. NSA ID, friend code, Discord user lookup
      • Set Nintendo Switch user visibility, i.e. which users appear to the app
      • Revoke sessions/authorisations
    • OAuth 2 token endpoint:
      • client_credentials grant
      • refresh_token grant
      • authorization_code grant
        • PKCE
      • implicit grant
      • password grant - nxapi-auth uses external authentication/public key WebAuthn credentials; it does not support password credentials that could be used with this grant
      • urn:ietf:params:oauth:grant-type:device_code grant - not currently planned
    • OAuth client authentication:
      • none
      • client_secret_post
      • client_secret_basic
      • private_key_jwt, client assertion types:
        • urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    • OAuth authorisation endpoint
    • Presence API
    • Play activity API
    • Nintendo Switch users API
    • nxapi-auth profile API
    • WebFinger API:
      • Coral friend code URL, e.g. https://lounge.nintendo.com/friendcode/0000-0000-0000/0000000000 (friend code hash not validated) - requires authentication (ll:fc), only returns known users (unless ll:fa)
      • NSA ID, e.g. https://nxapi-auth.fancy.org.uk/user/0000000000000000 - requires authentication (ll:ns), only returns known users
      • Nintendo Switch friend code, e.g. https://nxapi-auth.fancy.org.uk/friendcode/0000-0000-0000 - requires authentication (ll:fc), only returns known users (unless ll:fa)
      • nxapi-auth profile ID, e.g. https://nxapi-auth.fancy.org.uk/profile/AAAAAAAAAAAAAAAAAAAAAA
      • nxapi-auth profile username, e.g. https://nxapi-auth.fancy.org.uk/@user
      • Discord user ID, e.g. https://discord.com/users/0 - requires authentication (ll:ed)
      • Splashcat username, e.g. https://splashcat.ink/@user/ - requires authentication (ll:ei)
    • Coral f-generation and request encryption API

Profile customisation

The last Discord user used to sign in is used to set user display name, avatar, and banner. If no Discord user is linked, the display name can be updated within nxapi-auth and no avatar or banner can be set. The display name within nxapi-auth is private but can be shared with authorised third-party apps.

In public profile pages, the Nintendo Switch user name and icon is used and cannot be set within nxapi-auth. If a Discord user is linked, the last Discord user used to sign in is used to set the public profile page's banner image/colour. If the profile page has a Splashcat user linked, the favourite colour is used instead if set.

If the Discord user is a member of the Nintendo APIs and nxapi server, server profile data is used instead of global profile data if set.