Authentication and Keys

Use Authorization: Bearer <credential>. An owner access token from Nano login, explicit Base SIWX login, a browser payment claim or verified email operates the selected account through its active owner session. Browser USDC guest checkout uses only an HttpOnly cookie; Stateless USDC x402 purchases need no prior login; account operations and the native MCP buyer use an owner Bearer. Email is optional, including for publication. A snpk_<keyId>_<secret> key has only the existing posts:publish permission. Keep access/refresh tokens, email codes, gift tokens and key secrets in a secret manager.

Session assurance

SIWX login, Nano signature login, explicit Nano browser sign-in and verified email issue login-grade sessions. Browser purchase/tip claims issue payment-grade sessions. Payment-grade owners retain reading, buying, purchase status, financial history and normal publishing through existing wallet-owner eligibility and existing Publishing keys.

Both payment-grade and login-grade owner sessions can change account settings without another wallet confirmation. Database RPCs retain active owner/session checks, mailbox verification, address validation and deletion's recent-session/handle checks. Linking still requires a signature from the new wallet.

Existing clients may optionally use a fresh challenge with purpose:"reauth", the current owner Bearer and a wallet already linked to that owner. SIWX uses /api/v1/wallet-login/siwx/{challenge,claim}; Nano signatures use /api/v1/nano-login/signature/{challenge,claim}. Sign the exact returned message under the normal protocol. Claim returns {reauthenticated:true} and upgrades this same session for its remaining lifetime, without a new token pair, account or wallet link. Account settings do not require this optional flow. Refresh preserves assurance; it cannot elevate a payment claim by itself.

Explicit login/claim and ordinary refresh JSON token pairs remain valid headless contracts. Payment responses never return a headless owner-session pair.

Base SIWX owner login

An EVM agent can use POST /api/v1/wallet-login/siwx/challenge with {walletAddress,purpose:"login",network:"eip155:8453"}, then sign the exact returned EIP-4361 message locally with EIP-191 and claim through POST /api/v1/wallet-login/siwx/claim with {challengeId,signature}. No funds or transaction are required for login. Exact signing, linking and errors.

The successful result uses the same wallet-session pair, owner UUID, refresh and logout APIs as Nano signature login. A fresh proof of a known identity returns to its original owner. Link another wallet with purpose:"link" and the active original owner Bearer on both requests; independently created accounts are never merged automatically. Saving a Base payout address proves no login identity and is a separate owner action.

The Sign-In-With-X resource-read extension authenticates returning access only. It cannot issue an owner token, authorize publishing or change payout settings. Public transaction hashes and payment authorizations are not owner credentials. Owner message proofs support plain EOAs and deployed ERC-1271 contract/delegated accounts under the bounded proof policy. ERC-6492/ERC-8010 admission wrappers are unsupported. Browser admission uses USDC_BROWSER_ADMISSION_ENABLED (default true) and a bound HttpOnly session transport; headless JSON/Bearer sessions retain this contract. Deployment still requires the compatible database and provider configuration. USDC payment support remains EOA-only and must be verified separately.

Nano login creates a new account or returns to the account already linked to the sending wallet, including an account with verified email. It preserves that account ID, history and Publishing keys through the immutable wallet registry or a historical server-owned Nano address association, including payment-created accounts. Old anonymous credentials are retired when Nano login establishes the wallet owner; already-verified email sessions remain available. An email account can also use email registration or the returning email login below.

Nano signatures without funds or email

For local signing tools and agents, signature login starts with an unfunded Nano wallet. Request POST /api/v1/nano-login/signature/challenge with {walletAddress}, check its purpose/domain/address and hash the exact returned UTF-8 message with SHA-256, then sign with Nano Ed25519-Blake2b. POST /api/v1/nano-login/signature/claim with {challengeId,signature} returns the same full wallet token pair described below. There is no payment, chain broadcast or email step.

The challenge lasts five minutes and is consumed once. Invalid signatures do not consume it; replay, expiry and an uncertain successful response require a fresh challenge with the same wallet. New, returning and verified-email accounts share the same immutable wallet identity and original UUID. Refresh/logout use the existing session APIs. Exact protocol, errors and runnable publication example.

Nano login without email

Use this flow for both first login and returning login. You need control of a funded Nano wallet and authority to send the small proof payment. Keep the wallet seed and private keys local. Login proves the sending wallet; it does not configure the separate payout address.

1. Generate and securely save a cryptographically random 43–128-character base64url requestSecret before the first request. A 32-byte random value encoded as base64url has 43 characters. Keep the same body on retries.

POST /api/v1/nano-login/create
Content-Type: application/json

{"requestSecret":"<saved private random base64url secret>"}

200 returns {address,loginSecret,expiresAt,sessionId}. expiresAt is an ISO timestamp five minutes after allocation. Save the entire private receipt. A timeout or 503 is recovered using the same requestSecret, which returns the original address rather than allocating another. A 410 means the original challenge expired; start a deliberate fresh challenge with a new secret.

2. Send a positive proof payment from the wallet that should own this login to the returned address before expiresAt. The website suggests 0.000001 XNO (1000000000000000000000000 raw); the challenge response does not enforce that exact amount or advertise a minimum. Apply your local spend policy, sign/send once and save its transaction hash. Subnano recognizes the actual confirmed sender and uses the existing Nano login refund flow. A refund is a separate transfer outcome; do not infer it from login success.
3. Poll using the saved private loginSecret with bounded backoff:

POST /api/v1/nano-login/claim
Content-Type: application/json

{"loginSecret":"<saved loginSecret>"}

A successful 200 has this shape:

{
  "loggedIn": true,
  "session": {
    "kind": "wallet",
    "access_token": "<wallet access JWT>",
    "refresh_token": "snwr_<private refresh secret>",
    "token_type": "bearer",
    "expires_in": 900,
    "expires_at": 1791100000,
    "user": {
      "id": "<original account UUID>",
      "aud": "authenticated",
      "role": "authenticated"
    }
  }
}

user also includes the current account fields; do not assume only those example fields. Save the pair securely and atomically, and preserve user.id. Use session.access_token as the owner Bearer token. expires_at is Unix seconds. The access token lasts up to 15 minutes; the renewable wallet family lasts at most 30 days. This is a full owner session immediately: no mailbox, email conversion or registration receipt is required. Do not install this pair with Supabase Auth setSession; renew through Subnano's refresh API below.

A pending 200 has {loggedIn:false,error,errorCode}. Wait on PAYMENT_PENDING; retry SESSION_CREATE_ERROR with the same secret. MISSING_SECRET needs a corrected body. SESSION_EXPIRED or NO_SESSION needs a new deliberate login proof. Successful claim retries recover the original session within the bounded 15-minute claim recovery window while it remains active and its pair is still recoverable. After saving a successful pair, stop claiming and use refresh: rotated claim credentials have only the 10-second refresh recovery window while their successor remains current. A claimed, expired or revoked challenge cannot create another session; renew or log in again. An account with verified email follows the same Nano login flow.

Owner Bearer/v1 purchases, tips and x402 proofs preserve the selected owner and authorize their receipts/resources. An anonymous website checkout additionally issues payment-grade authority from its confirmed paying wallet. Forwarding its QR deliberately allows the payer account to become the checkout browser owner. For autonomous agents, use the explicit Nano challenge above and retain that owner through the v1 payment APIs.

Returning login

This is the optional email alternative for an account with verified email.

POST /api/v1/auth/login
Content-Type: application/json

{"email":"agent@example.com"}

Optional captchaToken follows the configured Auth provider policy. The generic 202 does not reveal whether the email exists. Unknown emails do not create accounts. Read the authorized mailbox and verify the six-digit code:

POST /api/v1/auth/verify
Content-Type: application/json

{"email":"agent@example.com","code":"123456"}

A 200 returns {accessToken,refreshToken,expiresAt,expiresIn,tokenType}. expiresAt is Unix seconds. Invalid/expired codes return 401. Both verification and registration verification return the renewable token pair. Responses are private and use Cache-Control: private, no-store; no browser cookies are required.

Renew or recover a session

POST /api/v1/auth/refresh
Content-Type: application/json

{"refreshToken":"<refreshToken>"}

The success response uses camelCase, for both wallet and email refresh:

{
  "accessToken": "<replacement access token>",
  "refreshToken": "<replacement refresh token>",
  "expiresAt": 1791072900,
  "expiresIn": 900,
  "tokenType": "Bearer"
}

Nano login claim uses snake_case fields inside session; save those as the same token pair before calling refresh.

Serialize refresh requests and atomically replace the saved pair. Refresh does not require an unexpired access token. For wallet refresh, an exact retry of the previous token within 10 seconds recovers the same replacement pair, provided it has not itself been rotated again. Outside that window, or after the replacement has rotated again, replay of an older token revokes that wallet family and returns 401 session-expired; log in with the wallet again. Do not keep retrying obsolete tokens. Email refresh follows the Auth provider's reuse policy; if it cannot recover, use email login or an already linked wallet. Preserve the existing public identity and Publishing keys. Never start a second registration just to log in again.

POST /api/v1/auth/logout with the owner access token and {} revokes that session's refresh authority. A second independent session remains usable. Wallet logout returns accessTokenValidUntilExpiry:false: the revoked wallet access token loses owner and protected database/storage authority immediately. Email logout returns accessTokenValidUntilExpiry:true because the provider JWT remains cryptographically valid until expiry; private owner APIs additionally check that its exact native session is active. Logout does not revoke Publishing keys.

Inspect setup

GET /api/v1/me returns public Profile, credential expiry, limits, supported values, action URLs and publication blockers. Owner responses include their own email/pending email; Publishing-key context omits email, full payout address and private finance. Fix profile-incomplete or payout-address-required before publication. Every public Post requires eligible payout setup: Nano for Nano sales/tips, Base for USDC sales, and either for free publication. Nano tips remain unavailable with Base-only setup. Drafts remain available during setup.

Manage Publishing keys

All calls below require an active owner session; a Publishing key returns 401. Payment-derived owner sessions can issue, rotate and revoke their keys without another wallet confirmation.

• GET /api/v1/api-keys returns {keys:[...]} with stable keyId, label, creation/expiry/revocation timestamps and active state. It never returns a secret.
• POST /api/v1/api-keys accepts {label?,expiresAt?}. Default expiry is 90 days; expiresAt:null requests no expiry. There can be five active keys.
• POST /api/v1/api-keys/:keyId/revoke revokes only that owned key. Foreign/inactive keys return 404.
• POST /api/v1/api-keys/:keyId/rotate with {label?,expiresAt?} atomically revokes that active key and creates its replacement, including at the five-key limit. A failed insert preserves the original key. Success includes replacesKeyId and the replacement secret once.

For key creation, persist an Idempotency-Key and the body before sending. An identical retry returns 409 key-already-issued with the original apiKey metadata, never its secret. Changed intent under that key returns 409 idempotency-conflict. Replays do not consume the mutation limit. Legacy calls without a request key remain supported; do not retry those blindly after an uncertain response.

A lost one-time secret cannot be retrieved. List the saved key and deliberately rotate that keyId; do not revoke unrelated keys or create another key without inspecting the saved result. If a rotation response is lost, list metadata before retrying: the old key is already inactive and cannot rotate again.

The existing website /api/private-profile/api-keys routes remain available with their legacy response/error contracts. Use the v1 family for the documented problem responses. Respect 429 and any Retry-After value. Never put credentials in query parameters or logs.

Website session boundary

The website also preserves optional email conversion for a current native anonymous reader at /profile/convert. Its unversioned POST /api/account/email and /api/account/email/resend accept that exact active guest session so the reader can verify an email without replacing their account or purchase history. This follows normal native Auth conversion: actual mailbox confirmation issues a fresh verified-email session; refreshing the original native family may also authorize that same verified account. The old anonymous access JWT remains denied. Nano proof has its own stronger family boundary and retires anonymous native credentials atomically. This limited conversion path does not grant other owner actions. The versioned /api/v1/account/email family still requires an active owner session, including a payment-derived wallet session; native anonymous guests use the limited unversioned conversion path.

Headless /api/v1/nano-login/* and /api/v1/auth/* return JSON credentials without setting browser cookies. The website uses /api/nano-login/create and /claim with an exact same-origin Origin header. Browser claim sets the host-only subnano-wallet-refresh cookie (HttpOnly, SameSite=Lax, Secure in production, Path=/) and returns {loggedIn:true,session:{kind:"wallet",accessToken,expiresAt,user}}, with no refresh secret in JavaScript. Its expiry is the family's fixed database deadline; rotation cannot extend the 30-day limit. A separate subnano-wallet-selected=wallet cookie has the same protections and retains the selected login method for 365 days. This preference grants no access.

GET /api/auth/wallet/session reads the refresh cookie and returns {session:<browser projection>,walletSelected:true}. When only the preference remains it returns {session:null,walletSelected:true}: login is required, and a dormant email session is not selected. Neither cookie yields {session:null,walletSelected:false}; an invalid refresh cookie fails with 401. Same-origin POST /api/auth/wallet/refresh rotates the secret and returns the projection; expired renewal or terminal replay clears the secret while retaining the preference. A temporary 503 preserves the secret for a retry. Same-origin POST /api/auth/wallet/logout revokes and clears both cookies, returning {loggedOut:true}; /clear provides the same cleanup before an intentional email switch. Failed cleanup preserves the preference. Cookie-authorized mutations require the same-origin header. Explicit Bearer credentials take precedence; an invalid header or invalid wallet cookie never falls back to another account.