Authentication — API reference • URnetwork

POST/auth/loginPublicAuth Login

Start a login for a user authority. The user authority may be:

email
phone number
Apple JWT
Google JWT
a wallet (wallet_auth): a Solana or Bittensor signature over the single-use challenge from /auth/wallet-challenge. A bound wallet returns network.by_jwt; an unbound wallet echoes wallet_auth and the client continues to /auth/network-create with a fresh challenge.
a seedphrase

Request bodyshow schema

user_auth

string

email or phone number

auth_jwt

string

auth_jwt_type

string

enum: apple, google

wallet_auth

WalletAuthArgs

wallet_address

string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message

string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature

string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain

string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor

wallet_nonce

string

The single-use nonce from /auth/wallet-nonce, embedded in wallet_message and echoed here. Optional during the client rollout; enforced whenever it is present. The newer /auth/wallet-challenge flow supersedes it.

seedphrase

string

The recovery seedphrase, for a seedphrase login.

Responses1 status · show schema

200

user_name

string

user_auth

string

email or phone number

auth_allowed

array<string>

The sign-in methods on file for this user authority

array

string

enum: password, email, phone, apple, google, solana, bittensor, seedphrase

error

object

suggested_user_auth

string

enum: password, apple, google

message

string

network

object

by_jwt

string

wallet_auth

WalletAuthArgs

wallet_address

string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message

string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature

string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain

string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor

wallet_nonce

string

The single-use nonce from /auth/wallet-nonce, embedded in wallet_message and echoed here. Optional during the client rollout; enforced whenever it is present. The newer /auth/wallet-challenge flow supersedes it.

Requestapplication/json

{
  "user_auth": "[email protected]",
  "auth_jwt": "string",
  "auth_jwt_type": "apple",
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana",
    "wallet_nonce": "string"
  },
  "seedphrase": "string"
}

Response200

{
  "user_name": "string",
  "user_auth": "[email protected]",
  "auth_allowed": [
    "password"
  ],
  "error": {
    "suggested_user_auth": "password",
    "message": "string"
  },
  "network": {
    "by_jwt": "string"
  },
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana",
    "wallet_nonce": "string"
  }
}

POST/auth/wallet-challengePublicAuth Wallet Challenge

Issue a single-use wallet sign-in challenge. The wallet signs the returned message_template byte for byte; the signature is then submitted as wallet_auth to /auth/login, /auth/network-create or /auth/add-auth, each of which consumes one challenge. The message is exactly three LF-separated lines: Sign in to URnetwork, Challenge: and Timestamp: ; the server rejects any other text (400 invalid message format), a challenge that is unknown, expired (5 minutes), already used, issued for another blockchain or address, or whose timestamp differs from the issued one. Bittensor (TAO) wallets sign with sr25519 in the substrate context; both the raw text and the polkadot-js …-wrapped form of the signature verify, and the unwrapped text is what the client submits. Rate limited per client address. See server/BITTENSOR-LOGIN.md.

Request bodyshow schema

blockchain

string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor

wallet_address

string

Optional. Solana base58 public key or Bittensor ss58 address; when given, the challenge is bound to it.

Responses1 status · show schema

200

challenge

string

32 random bytes, base64url; embedded in message_template

timestamp

integer

unix seconds the challenge was issued; embedded in message_template

expires_in

integer

seconds until the challenge expires (300)

message_template

string

The exact text to sign: Sign in to URnetwork Challenge: Timestamp:

error

object

message

string

Requestapplication/json

{
  "blockchain": "solana",
  "wallet_address": "string"
}

Response200

{
  "challenge": "string",
  "timestamp": 0,
  "expires_in": 0,
  "message_template": "string",
  "error": {
    "message": "string"
  }
}

POST/auth/wallet-noncePublicAuth Wallet Nonce

Issue a fresh single-use, short-lived (5 minute) nonce for wallet login. The client embeds the returned nonce in the message it signs and echoes it back as wallet_auth.wallet_nonce; the server validates and consumes it in the same transaction as the login, so a captured (message, signature) pair cannot be replayed. The nonce is optional during the client rollout and enforced whenever it is present.

This is the older, narrower anti-replay token. /auth/wallet-challenge supersedes it: that one returns the exact message text to sign and binds the challenge to a blockchain and an address.

Responses1 status · show schema

200

nonce

string

Single-use, expires in 5 minutes. Embed it in the signed message and echo it as wallet_auth.wallet_nonce.

POST/auth/login-with-passwordPublicAuth Login With Password

Password login for email and phone number.

Request bodyshow schema

user_auth

string

email or phone number

password

string

verify_otp_numeric

boolean

Responses1 status · show schema

200

verification_required

object

user_auth

string

email or phone number

network

object

by_jwt

string

name

string

error

object

message

string

Requestapplication/json

{
  "user_auth": "[email protected]",
  "password": "string",
  "verify_otp_numeric": false
}

Response200

{
  "verification_required": {
    "user_auth": "[email protected]"
  },
  "network": {
    "by_jwt": "string",
    "name": "string"
  },
  "error": {
    "message": "string"
  }
}

POST/auth/verifyPublicAuth Verify

Verify ownership of email or phone number.

Request bodyshow schema

user_auth

string

email or phone number

verify_code

string

Responses1 status · show schema

200

network

object

by_jwt

string

error

object

message

string

GET/auth/refreshBearer authAuth Refresh Token

Refresh the client JWT (by_jwt) for the caller's client. Requires a client JWT (from /network/auth-client).

Responses1 status · show schema

200

by_jwt

string

The refreshed client JWT.

error

object

message

string

POST/auth/verify-sendPublicAuth Verify Send

Send verification code to email or phone number.

Request bodyshow schema

user_auth

string

email or phone number

use_numeric

boolean

optionally create a numeric 6 digit code instead of the default 8 digit

Responses1 status · show schema

200

user_auth

string

email or phone number

POST/auth/password-resetPublicAuth Password Reset

Send password reset code to email or phone number.

Request bodyshow schema

user_auth

string

email or phone number

Responses1 status · show schema

200

user_auth

string

email or phone number

POST/auth/password-setPublicAuth Password Set

Change password.

Request bodyshow schema

reset_code

string

password

string

Responses1 status · show schema

200

empty object

POST/auth/network-checkPublicAuth Network Check

Check if the network name is available. The name is normalized before it is checked: trimmed, lower-cased, and spaces replaced with dashes. The normalized name must satisfy:

at least 5 characters
at most 50 characters
only lowercase letters, digits and dashes

and must not be within one edit of an existing network name.

Request bodyshow schema

network_name

string

Responses1 status · show schema

200

available

boolean

POST/auth/network-createPublicauthNetworkCreate

Create a new network. A user authority can be associated with at most one network.

Request bodyshow schema

user_name

string

user_auth

string

email or phone number

auth_jwt

string

auth_jwt_type

string

enum: apple, google

password

string

network_name

string

terms

boolean

user consent to accept terms of service

verify_use_numeric

boolean

wallet_auth

WalletAuthArgs

wallet_address

string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message

string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature

string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain

string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor

wallet_nonce

string

The single-use nonce from /auth/wallet-nonce, embedded in wallet_message and echoed here. Optional during the client rollout; enforced whenever it is present. The newer /auth/wallet-challenge flow supersedes it.

referral_code

string

Optional referral code of the network that referred this new network.

balance_code

string

Optional balance code to add transfer balance to the new network.

product_updates

boolean

The sign-up form's "Periodic product updates" line. Absent = true (the line ships ticked). false turns the product-updates preference off from the first moment: no onboarding campaign mail is ever sent. Honored on every create path, including sign-ups that complete through /auth/verify. The server records a signup.optout_changed event with the value.

Responses2 statuses · show schema

200

network

object

by_jwt

string

network_id

string

uuid

network_name

string

is_pro

boolean

user_auth

string

email or phone number

seedphrase

string

The generated recovery seedphrase, returned once on the seedphrase sign-up path. It is never retrievable again.

is_pro

boolean

verification_required

object

user_auth

string

email or phone number

error

object

message

string

400

No body

Requestapplication/json

{
  "user_name": "string",
  "user_auth": "[email protected]",
  "auth_jwt": "string",
  "auth_jwt_type": "apple",
  "password": "string",
  "network_name": "string",
  "terms": false,
  "verify_use_numeric": false,
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana",
    "wallet_nonce": "string"
  },
  "referral_code": "string",
  "balance_code": "string",
  "product_updates": false
}

Response200

{
  "network": {
    "by_jwt": "string",
    "network_id": "00000000-0000-0000-0000-000000000000",
    "network_name": "string",
    "is_pro": false
  },
  "user_auth": "[email protected]",
  "seedphrase": "string",
  "is_pro": false,
  "verification_required": {
    "user_auth": "[email protected]"
  },
  "error": {
    "message": "string"
  }
}

Response400

// no body

POST/auth/network-deleteBearer authAuth Network Delete

Delete network

Responses1 status · show schema

200

error

object

message

string

POST/auth/code-createBearer authAuth Code Create

Create a limited use code (auth code) to share authentication with connected apps and tools. The code is tied to the caller session, and will be expired with any of the caller's sessions. This is a subset of an OAuth flow. For the full OAuth 2.1 / OpenID Connect flow see the oauth routes.

Request bodyshow schema

duration_minutes

number

uses

integer

roles

array<string>

Optional. Identity roles carried by logins minted from this code. Only a network session may set these. The values have no meaning to the network.

array

string

principal

string

Optional. Identity principal carried by logins minted from this code. Only a network session may set this.

Responses1 status · show schema

200

auth_code

string

duration_minutes

number

uses

integer

error

object

auth_code_limit_exceeded

boolean

message

string

Requestapplication/json

{
  "duration_minutes": 0,
  "uses": 0,
  "roles": [
    "string"
  ],
  "principal": "string"
}

Response200

{
  "auth_code": "string",
  "duration_minutes": 0,
  "uses": 0,
  "error": {
    "auth_code_limit_exceeded": false,
    "message": "string"
  }
}

GET/auth/apple/callbackPublicauthAppleCallbackGet

Parameters

state(query)

string

required

id_token(query)

string

code(query)

string

user(query)

string

error(query)

string

Responses2 statuses · show schema

302

No body

400

No body

POST/auth/apple/callbackPublicauthAppleCallback

Apple has no SDK for android, windows or linux, so those apps open Apple's authorize page in the system browser (a Custom Tab on android) with client_id = the Apple Services ID, redirect_uri = this endpoint, response_type=code id_token, response_mode=form_post, scope=name email, and a fresh state and nonce per attempt. Apple posts the result here as a form, and this endpoint answers 302 to the app's own scheme so the browser hands control back to the app:

://oauth/apple?state=…&id_token=…&code=…&user=… ://oauth/apple?state=…&error=…

user is the JSON name/email Apple sends with the first authorization only. Nothing is stored or verified here: the app checks that state is the attempt it started and that the identity token's nonce claim is the one it minted, then signs in with the token through POST /auth/login (auth_jwt_type: apple), which verifies the signature and the audience.

state is opaque except for one optional claim: when it is the base64url encoding of a JSON object with a platform key, that key picks the scheme (android → ur://, windows and linux → urnetwork://); without it the android scheme is used. GET with the same parameters as a query behaves the same way (manual testing).

Request bodyshow schema

state

string

The attempt's state, echoed by Apple untouched.

code

string

Apple's authorization code (unused by the apps, passed through).

id_token

string

Apple's identity token (a JWT carrying the attempt's nonce).

user

string

JSON with the user's name and email, first authorization only.

error

string

Apple's error, e.g. user_cancelled_authorize.

Responses2 statuses · show schema

302

No body

400

No body

GET/auth/google/callbackPublicauthGoogleCallback

Windows and Linux have no native Google sign-in, so those apps open Google's authorize page in the system browser with client_id = the ur.io web sign-in client, redirect_uri = this endpoint, response_type=code, scope=openid email profile, prompt=select_account, and a fresh state and nonce per attempt (android signs in with play services and ur.io in the page; neither uses this). Google redirects the browser here with the authorization code; this endpoint exchanges it at Google's token endpoint with the web client's secret (vault google.yml sign_in_oauth) and answers 302 to the app's own scheme so the browser hands control back to the app:

://oauth/google?state=…&id_token=… ://oauth/google?state=…&error=…

Nothing is stored. The app checks that state is the attempt it started and that the identity token's nonce claim is the one it minted, then signs in with the token through POST /auth/login (auth_jwt_type: google), which verifies the signature and the audience.

state is opaque except for the optional platform claim shared with the Apple callback: base64url JSON with a platform key picks the scheme (android → ur://, windows and linux → urnetwork://); without it the android scheme is used. Google's own error (e.g. access_denied) is passed through; a failed exchange or a missing client configuration comes back as error too (not_configured when the vault has no sign_in_oauth).

Parameters

state(query)

string

The attempt's state, echoed by Google untouched.

required

code(query)

string

Google's authorization code, exchanged here for the identity token.

error(query)

string

Google's error, e.g. access_denied.

Responses3 statuses · show schema

302

No body

400

No body

405

No body

POST/auth/code-loginPublicAuth Code Login

Authenticate with an auth code. The returned session is tied to the session that created the auth code, and will be expired with any of the creator's sessions. This is a subset of an OAuth flow.

Request bodyshow schema

auth_code

string

Responses1 status · show schema

200

by_jwt

string

error

object

message

string

POST/auth/add-authBearer authAuth Add Auth

Add an authentication method (email/phone + password, SSO, or wallet) to the calling user. A wallet (wallet_auth, Solana or Bittensor) must sign the single-use challenge from /auth/wallet-challenge, the same proof as wallet login; one wallet address binds to one user. Subject to the account action rate limit.

Request bodyshow schema

user_auth

string

email or phone number

auth_jwt

string

auth_jwt_type

string

enum: apple, google

password

string

wallet_auth

WalletAuthArgs

wallet_address

string

Solana base58 public key, or Bittensor ss58 address (prefix 42, checksum verified)

wallet_message

string

The message_template issued by /auth/wallet-challenge, unmodified (no wrapper, LF line endings)

wallet_signature

string

Solana: base64 ed25519 signature over the message. Bittensor: hex of the 64-byte sr25519 signature (with or without 0x) made in the substrate signing context, over the raw or -wrapped message

blockchain

string

solana (default) or tao/bittensor; case-insensitive

enum: solana, tao, bittensor

wallet_nonce

string

The single-use nonce from /auth/wallet-nonce, embedded in wallet_message and echoed here. Optional during the client rollout; enforced whenever it is present. The newer /auth/wallet-challenge flow supersedes it.

Responses1 status · show schema

200

error

object

message

string

Requestapplication/json

{
  "user_auth": "[email protected]",
  "auth_jwt": "string",
  "auth_jwt_type": "apple",
  "password": "string",
  "wallet_auth": {
    "wallet_address": "string",
    "wallet_message": "string",
    "wallet_signature": "string",
    "blockchain": "solana",
    "wallet_nonce": "string"
  }
}

Response200

{
  "error": {
    "message": "string"
  }
}

POST/auth/remove-authBearer authAuth Remove Auth

Remove an authentication method from the calling user. The last remaining method cannot be removed.

Request bodyshow schema

auth_type

string

The sign-in method to remove; the last remaining method cannot be removed

enum: email, phone, apple, google, solana, bittensor, seedphrase

Responses1 status · show schema

200

error

object

message

string

POST/auth/generate-seedphraseBearer authAuth Generate Seedphrase

Generate a recovery seedphrase for the calling user. Fails if a seedphrase auth already exists; see /auth/regenerate-seedphrase.

Responses1 status · show schema

200

seedphrase

string

error

object

message

string

POST/auth/regenerate-seedphraseBearer authAuth Regenerate Seedphrase

Replace the calling user's recovery seedphrase with a new one, invalidating the previous seedphrase.

Responses1 status · show schema

200

seedphrase

string

error

object

message

string