Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Authentication
Authentication is how three.ws knows who you are: it protects your agents, your avatars, and your dashboard, and it is required for anything that writes data. Sign in at three.ws/login with a crypto wallet or a plain email/social account; developers can also mint API keys for scripts and servers.
three.ws supports four authentication methods. Which one you need depends on how you're building:
| Method | Best for |
|---|---|
| Sign-In With Solana (SIWS) | Users with a Solana wallet (Phantom, Backpack, Solflare, Seeker). Solana is the home chain; this is the default wallet sign-in. |
| Sign-In With Ethereum (SIWE) | Users with an EVM browser wallet (MetaMask, Coinbase Wallet, etc.) |
| Privy | Users without a wallet: email code sign-in, plus Privy-managed wallet login |
| Sign in with X | Users who already connected an X (Twitter) account, or want a passwordless account from one |
| API keys | Server-to-server and programmatic access |
Authentication controls who can edit or publish an agent, which agents a user owns (for on-chain operations), rate limiting and usage tracking, and access to the dashboard and API.
Sign-In With Solana (SIWS)
SIWS (CAIP-122) lets users authenticate by signing a message with their Solana wallet. No password, no email, no transaction, no fees. This is the platform's own rail: the nonce and the session both come from three.ws, with no third-party auth service in the path.
Supported wallets
- Phantom (
window.phantom.solana) - Backpack (
window.backpack.solana) - Solflare (
window.solflare) - Solana Seeker / Seed Vault (the three.ws mobile app injects a one-tap wallet; see below)
- Any wallet exposing the standard
connect()+signMessage()provider interface
How the flow works
- Your frontend calls
GET /api/auth/siws/nonce. The response carries a one-time nonce (valid 5 minutes), a CSRF token, and the canonicaldomainandurito sign against. The endpoint also sets a__Host-csrf-siwscookie. - You build a CAIP-122 message using the nonce and the server-provided domain and URI.
- The user signs the message in their wallet (a free, off-chain ed25519 signature).
- You
POST /api/auth/siws/verifywith the raw message and the signature (base58 or base64 encoded), plus the CSRF token as anX-CSRF-Tokenheader. - The backend parses the message, checks domain and URI against the deployment, checks the chain id (
mainnet,devnet, ortestnet), checks the time window, burns the nonce (single use), verifies the ed25519 signature recovers the claimed address, and issues a session cookie.
Always build the message from the domain and uri the nonce endpoint returns rather than location.host: that keeps dev frontends that proxy /api/* to a remote upstream (Codespaces tunnels, preview deploys) producing messages that pass the server's domain check.
API routes
| Method | Path | Description |
|---|---|---|
GET |
/api/auth/siws/nonce |
Generate a nonce + CSRF token; returns canonical domain/uri |
POST |
/api/auth/siws/verify |
Verify signed message, issue session |
POST |
/api/auth/logout |
Revoke session cookie |
Raw SIWS flow
This is the exact flow the three.ws login page runs (see public/login.html and src/privy-login.js, Solana branch):
// 1. Get nonce + CSRF token + canonical domain/uri
const { nonce, csrf, domain, uri } = await fetch('/api/auth/siws/nonce', {
credentials: 'include',
}).then((r) => r.json());
// 2. Connect the wallet
const provider = window.phantom?.solana ?? window.solana;
const { publicKey } = await provider.connect();
const address = publicKey.toString();
// 3. Build the CAIP-122 message. Put the Terms agreement in the signed
// statement so the signature itself evidences acceptance.
const statement =
'Sign in to three.ws. This request will not trigger any blockchain transaction or cost any fees. ' +
'By signing, you agree to the Terms of Service (https://three.ws/legal/tos) and Privacy Policy (https://three.ws/legal/privacy).';
const message = [
`${domain} wants you to sign in with your Solana account:`,
address,
'',
statement,
'',
`URI: ${uri}`,
'Version: 1',
'Chain ID: mainnet',
`Nonce: ${nonce}`,
`Issued At: ${new Date().toISOString()}`,
`Expiration Time: ${new Date(Date.now() + 5 * 60 * 1000).toISOString()}`,
].join('\n');
// 4. Sign (ed25519 over the utf8 bytes) and encode the 64-byte signature
const { signature: sigBytes } = await provider.signMessage(new TextEncoder().encode(message), 'utf8');
const signature = btoa(String.fromCharCode(...sigBytes)); // base58 also accepted
// 5. Verify: CSRF token in the header, tosAccepted because the statement
// carries the agreement
const res = await fetch('/api/auth/siws/verify', {
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json', 'x-csrf-token': csrf },
body: JSON.stringify({ message, signature, tosAccepted: true }),
});
const { user } = await res.json();
One-tap sign-in (Seeker / Seed Vault)
Wallets that implement the Sign In With Solana wallet feature expose signIn(), which merges authorization and the sign-in signature into a single wallet interaction. The three.ws mobile wallet advertises this with a supportsSignIn flag. When available, call signIn() with the same fields (domain, statement, uri, nonce, timestamps), then POST the wallet's signedMessageText and signature to the same verify endpoint. The server accepts the exact bytes the wallet signed. Wallets without signIn() fall through to the two-step connect() + signMessage() flow above.
Verify errors
| Status | Code | Meaning |
|---|---|---|
400 |
invalid_message |
Message is not parseable CAIP-122 |
400 |
invalid_domain / invalid_uri |
Domain or URI does not match this deployment |
400 |
invalid_chain |
Chain ID is not mainnet, devnet, or testnet |
400 |
expired / not_yet_valid |
Outside the message's time window |
400 |
invalid_nonce / nonce_reused / nonce_expired |
Nonce unknown, already burned, or past its 5-minute TTL |
401 |
invalid_signature |
Signature does not verify against the claimed address |
403 |
invalid_request |
CSRF header missing or does not match the __Host-csrf-siws cookie |
403 |
account_deleted |
Wallet belongs to a deleted account |
Sign-In With Ethereum (SIWE)
SIWE (EIP-4361) lets users authenticate by signing a message with their Ethereum wallet — no password, no email required.
Note that the login page has two EVM sign-in paths: the quick "connect wallet" button at the top runs SIWE through Privy (see the Privy section below), while the "Using on-chain features?" section runs the platform's own SIWE rail documented here. Both end in the same three.ws session; the own rail is the one to integrate against if you are building outside the Privy SDK.
Supported wallets
- MetaMask — browser extension,
window.ethereum - WalletConnect v2 — mobile wallets (Trust, Rainbow, MetaMask Mobile, and any WC-compatible wallet)
- Coinbase Wallet — browser extension or mobile
- Any EIP-1193 compliant provider
How the flow works
- Your frontend calls
GET /api/auth/siwe/nonceto get a one-time nonce (valid for 5 minutes) and a CSRF token. - You build an EIP-4361 message using the nonce, the user's address, and the current domain.
- The user signs the message in their wallet — this is a free, off-chain signature.
- You
POST /api/auth/siwe/verifywith the raw message and signature, plus the CSRF token as anX-CSRF-Tokenheader. - The backend verifies the signature recovers the claimed address, checks the nonce hasn't been used, validates the domain, and issues a session cookie.
The CSRF token is mandatory on the verify call. The nonce endpoint sets a __Host-csrf-siwe cookie and returns the CSRF value in the response body. Pass it as X-CSRF-Token on the verify POST to prevent cross-site attacks.
API routes
| Method | Path | Description |
|---|---|---|
GET |
/api/auth/siwe/nonce |
Generate a nonce + CSRF token |
POST |
/api/auth/siwe/verify |
Verify signed message, issue session |
POST |
/api/auth/logout |
Revoke session cookie |
Using the built-in controller
The ConnectWalletController class in src/wallet/connect-button.js handles the full SIWE flow including chain switching:
import { createConnectWalletButton } from '/src/wallet/connect-button.js';
const ctrl = createConnectWalletButton(document.getElementById('wallet-mount'), {
onSuccess(data) {
console.log('Signed in as', data.wallet.address);
}
});
This mounts a <button class="cwb-btn"> that steps through connecting, chain validation, signing, and verification. The controller fires change CustomEvents on state transitions.
For lower-level control, use ConnectWalletController directly:
import { ConnectWalletController } from '/src/wallet/connect-button.js';
const ctrl = new ConnectWalletController({
nonceUrl: '/api/auth/siwe/nonce',
verifyUrl: '/api/auth/siwe/verify',
allowedChainIds: [1, 8453, 10],
onSuccess(data) { /* ... */ }
});
ctrl.addEventListener('change', (e) => {
console.log('State:', e.detail.status, e.detail.address);
});
await ctrl.connect(); // request accounts
await ctrl.signAndVerify(); // sign message + post to backend
The state machine states (from src/wallet/state.js) are: idle → detecting → requesting_accounts → connected → signing → verifying → success (or error / wrong_chain at any point).
WalletConnect (mobile wallets)
For mobile wallet support without Privy, use the WalletConnect bridge:
import { signInWithWalletConnect } from '/src/auth/walletconnect-bridge.js';
const { user, address } = await signInWithWalletConnect();
This opens the WalletConnect QR modal, handles the SIWE sign flow, and sets the session cookie. Requires VITE_WALLETCONNECT_PROJECT_ID in your environment — get a project ID at cloud.walletconnect.com.
Raw SIWE flow (without the controller)
import { SiweMessage } from 'siwe';
// 1. Get nonce + CSRF token
const { nonce, csrf, expiresAt } = await fetch('/api/auth/siwe/nonce', {
credentials: 'include'
}).then(r => r.json());
// 2. Build the EIP-4361 message. Put the Terms agreement in the signed
// statement so the signature itself evidences acceptance.
const message = new SiweMessage({
domain: window.location.host,
address: walletAddress,
statement: 'Sign in to three.ws. This does not cost anything and proves wallet ownership. By signing, you agree to the Terms of Service (https://three.ws/legal/tos) and Privacy Policy (https://three.ws/legal/privacy).',
uri: window.location.origin,
version: '1',
chainId: 1,
nonce,
expirationTime: expiresAt,
}).prepareMessage();
// 3. Sign
const signature = await provider.getSigner().signMessage(message);
// 4. Verify: include the CSRF token in the header. Send tosAccepted: true
// when your UI displayed the Terms agreement (statement above or a notice
// next to the sign-in control); the server records the acceptance and the
// Terms version on the user record.
const res = await fetch('/api/auth/siwe/verify', {
method: 'POST',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrf,
},
body: JSON.stringify({ message, signature, tosAccepted: true }),
});
const { user, wallet } = await res.json();
Security note: Never submit the SIWE message to a domain other than where the nonce was issued. The backend validates that
domainanduriin the message match the deployment'sAPP_ORIGIN. Replaying a valid signature from a phishing page is rejected. A localhostdomainis accepted only by a deployment whose ownAPP_ORIGINis localhost, never by three.ws itself.A wallet whose account was closed through
DELETE /api/auth/megets403 account_deleted. Signing in again does not revive it: the same answer the SIWS and SAML paths give.
Terms of Service acceptance
Every auth endpoint accepts an optional tosAccepted: true body field. Send it whenever your UI showed the user the Terms of Service agreement (a checkbox, a "By signing in you agree" notice, or the agreement sentence inside the signed wallet statement). The server writes a durable acceptance record (audit log + the accepted Terms version on the user row). Two rules:
POST /api/auth/registerrequirestosAccepted: true; account creation without it fails with400 tos_required. Registration UIs must show a real agreement control.- Wallet and Privy verifies (
/api/auth/siwe/verify,/api/auth/siws/verify,/api/auth/privy/verify) andPOST /api/auth/logintreat it as an affirmation: acceptance is recorded on every sign-in, so users converge onto the current Terms version over time.
An already-signed-in user can also record acceptance directly with POST /api/legal/tos-ack { version?, context? }. That endpoint only covers the Terms of Service; the real-funds agreements (Risk Disclosure + Agent Wallet Agreement, required before any custodial money-moving action) are a separate, heavier signing flow at POST /api/legal/risk-ack (review them at /legal/agreements). Every custodial money endpoint (withdraw, trade, pay, launch) requires a typed-name signature of all three documents; an unsigned account gets 403 risk_ack_required over a session and an API key alike, and devnet actions are exempt. See risk acknowledgment.
Privy (Social / Email Auth)
Privy lets users log in with an email code, or with a wallet through Privy's auth service. Each Privy account gets a wallet managed by Privy's MPC system, so users get wallet-based identity without needing MetaMask or any browser extension.
Why use Privy
Not every user has a crypto wallet. If your audience includes non-web3 users, Privy removes the wallet prerequisite while still giving those users an Ethereum address they can use for on-chain operations later.
How it works
The three.ws login and register pages run Privy headless: our own UI drives @privy-io/js-sdk-core directly (see src/privy-login.js), so there is no Privy-hosted modal.
- The frontend reads the app id from
GET /api/config(privyAppId) and constructs the SDK client. - Email:
privy.auth.email.sendCode(email, captchaToken)sends a 6-digit code;privy.auth.email.loginWithCode(email, code)exchanges it for an identity token (a JWT signed with Privy's ES256 key). - EVM wallet: the page runs Privy's SIWE ceremony (
siwe/initfor a nonce and message,personal_signin the wallet,loginWithSiweto finish) and gets the same kind of identity token. - The frontend posts that token to
POST /api/auth/privy/verify. - The backend fetches Privy's JWKS, verifies the token signature and audience, and finds-or-creates the user record (keyed on the Privy DID). A first Privy sign-in carrying an email links to an existing account with that email only when three.ws has verified the address; an account registered with an unverified email is left alone and the Privy identity gets its own account, so nobody can pre-register a stranger's address and catch their sign-in. SAML and wallet sign-ins follow the same rule.
- Linked wallets are synced best-effort from Privy's server API into the user's wallet list; a login with no wallet still succeeds.
- A session cookie is issued; from this point the user is authenticated identically to a SIWS or SIWE user.
Solana wallet sign-in does not go through Privy at all: it uses the platform's own SIWS rail above.
CAPTCHA (Cloudflare Turnstile)
When CAPTCHA is enabled for the Privy app (Privy dashboard, Security tab), Privy rejects both passwordless/init (the email code send) and siwe/init (the wallet nonce) with 401 invalid_credentials unless the request carries a Turnstile token. Three things follow for anyone integrating headless:
- Fetch the app config (
GET https://auth.privy.io/api/v1/apps/{appId}with aprivy-app-idheader) to readcaptcha_enabledandcaptcha_site_key(Turnstile keys are prefixedt:), and load the Turnstile widget fromhttps://challenges.cloudflare.com/turnstile/v0/api.js. Run it ininteraction-onlyappearance so users only see it when Cloudflare requires an interaction. email.sendCodeaccepts the token as its second argument.siwe.initin@privy-io/js-sdk-corehas no token parameter, so the login page calls the init endpoint directly with{ address, token }, builds the standard EIP-4361 message from the returned nonce, and hands the wallet's signature plus that message tologinWithSiwe(signature, wallet, message). A401with codeinvalid_captchameans the token was read but failed verification;invalid_credentialsmeans no token reached Privy at all.
If the app config declares a custom_api_url (three.ws uses https://privy.three.ws), every auth call above goes to that domain instead of auth.privy.io.
The discovery step is factored into src/auth/privy-captcha.js, and the login page treats "CAPTCHA required" and "could not find out" as different answers: when the app config probe fails, the page refuses to send a code without a token Privy might require, and tells the user to reload rather than surfacing Privy's opaque 401 invalid_credentials. The same distinction applies to /api/config itself: if that probe fails (it is bounded to six seconds), the email and wallet controls are hidden with an explanation and the password form still signs the visitor in, instead of the whole block silently vanishing as it does when the deployment genuinely has no Privy app.
Configuration
# Client-side (Vite / browser)
VITE_PRIVY_APP_ID=your-privy-app-id
# Server-side (for token verification)
PRIVY_APP_ID=your-privy-app-id
Get both values from dashboard.privy.io. The server uses PRIVY_APP_ID to validate the JWT audience claim and to fetch the JWKS from https://auth.privy.io/api/v1/apps/{appId}/jwks.json.
Verify endpoint
// After the Privy client gives you an auth token. Send tosAccepted: true when
// your UI displayed the Terms of Service agreement next to the sign-in control;
// the server records the acceptance and the Terms version on the user record.
const res = await fetch('/api/auth/privy/verify', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token, tosAccepted: true }),
});
const { user } = await res.json();
// user: { id, email, display_name, plan, avatar_url, created_at }
// Any wallets Privy has linked are synced onto the account automatically;
// list them afterwards with GET /api/auth/wallets.
A Privy identity attached to an account that was closed through DELETE /api/auth/me gets 403 account_deleted instead of a session. Signing in again never revives a deleted account on any path.
Linking additional wallets
Once a user is signed in via Privy, they can connect a browser wallet and link it to their account via POST /api/auth/wallets. See the Multi-wallet section below.
Sign in with Google
Google sign-in is a direct OpenID Connect authorization-code flow with PKCE, run by api/auth/google/[action].js on top of the shared identity helpers in api/_lib/identities.js. There is no third-party SDK in the browser: the login page links to /api/auth/google/start, the server sends the browser to Google, and Google sends it back to /api/auth/google/callback.
How the flow works
GET /api/auth/google/start?next=/dashboardsigns a flow cookie (__Host-gsi, ten minutes) holding a randomstate, anonce, and a PKCE verifier, then redirects to Google's authorization endpoint withcode_challenge_method=S256,scope=openid email profileandprompt=select_account.- Google redirects to
/api/auth/google/callback?code=...&state=.... The server rejects astatethat does not match the flow cookie, exchanges the code for tokens with the verifier, and verifies the ID token against Google's published keys: signature, issuer, audience (the client id), expiry, and thenoncefrom the flow cookie. - What happens next depends on the account:
- The Google account is already linked. The person is signed in and sent to
next. - Not linked, and a three.ws account has the same email. Only when Google says
email_verifiedand the three.ws account verified that address too, the person sees a confirm page ("Link Google to your account?"). Nothing is linked until they choose Link and sign in, which posts to/api/auth/google/confirmwith a signed five-minute cookie (__Host-glink) carrying the verified claims. "Not my account" changes nothing. An account whose email was never verified on three.ws is never linked by email (the same rule Privy, SAML and wallet sign-ins follow), so nobody can pre-register a stranger's address and catch their sign-in; that account's owner links Google from Settings instead, where their session proves ownership. - No account at all. A new account is created from the verified claims, born
email_verified, with no password. Google is its sign-in method until the person sets a password or links a wallet.
- The Google account is already linked. The person is signed in and sent to
- Signing in creates a session and leaves every other session alone, so signing in from a second MCP client never signs the first out.
next is checked by the same safeNext rule as the rest of the login page: a relative path on this site, never an external URL. The MCP authorization screen passes next=/oauth/consent?..., which is how a person goes Google, back to three.ws, straight to the consent screen.
Linking and unlinking from Settings
Settings, Sign-in methods lists every way into the account (password, email code, wallets, Google) and offers:
- Link Google (
/api/auth/google/start?intent=link, session required): the same round trip, ending with the Google account linked to the signed-in user. A Google account linked to a different three.ws account is refused withidentity_in_use; a second, different Google account on the same user is refused withalready_linkeduntil the first is unlinked. - Unlink (
POST /api/auth/google/unlink, session and CSRF required): needs a fresh proof the person at the keyboard owns the account, either{ "password": "..." }in the body or having just completed/api/auth/google/start?intent=reauth, which forces Google to ask for credentials again (prompt=login,max_age=0, and the callback checksauth_time) and sets a five-minute__Host-reauthcookie. Without either, the route answers401 reauth_required. Google can never be unlinked when it is the only sign-in method (409 last_sign_in_method). - Status (
GET /api/auth/google/status):{ configured, google, password, email_code, wallets, count, reauthenticated }, which is what the card renders.
Error states
A failed login lands on /login?error=google_<code> with a message the page explains: google_cancelled (you closed Google's prompt), google_expired (the ten-minute flow cookie ran out or the state did not match), google_email_unverified (Google does not vouch for that address), google_unverified_account (a three.ws account has that email but never verified it), google_not_linked (you chose "Not my account"), google_identity_in_use, google_already_linked, google_invalid_token, google_exchange_failed, google_failed, and google_unavailable (not configured on this deployment). A failed link or re-authentication lands back on the settings card with ?google=<code> instead. Nothing ever surfaces as raw JSON in the address bar.
Configuration
# A "Web application" OAuth client in the Google Cloud console (APIs & Services,
# Credentials). Its authorized redirect URI must be exactly:
# https://<your origin>/api/auth/google/callback
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=
Both unset: GET /api/config reports googleEnabled: false, the login page shows no Google button, /api/auth/google/start sends a browser to /login?error=google_unavailable and answers an API caller 501 not_configured. Nothing else changes.
Sign in with Telegram, link codes and external wallets
Telegram sign-in (widget and deep-link magic link), one-time link codes for phones, desktop apps, the CLI and Telegram chats, and signed-message external wallets are documented in account-linking.md.
Sign in with X
GET /api/auth/x/login?next=<path> starts an OAuth 2.0 PKCE round trip with X
(the same client the Connect-X posting flow in the Herald and
Town already use) and redirects back through GET /api/auth/x/callback. It
only appears on /login when GET /api/config
reports xLoginEnabled: true, which requires X_OAUTH_CLIENT_ID and
X_OAUTH_CLIENT_SECRET; unconfigured, the endpoint answers 501 not_configured.
X's OAuth2 profile never reliably carries a verified email, so there is no email-matching step like Google's. Three outcomes, in order:
- Already linked (
user_identitieshas this X id) → signs straight in. - Already connected for posting (
social_connectionshas this X id from the Connect-X flow, but never linked for login) → links it and signs in, rather than creating a duplicate account. - Neither → creates a new passwordless account on the same
@wallet.localplaceholder email pattern SIWS and SIWE already use.
A failed or declined attempt redirects back to /login with an error code
(x_unavailable, rate_limited, and the standard OAuth failure codes) rather
than a bare error page.
Session Management
Sessions are stored server-side in Postgres. The browser receives an opaque token in a secure cookie.
Session cookie
__Host-sid
HttpOnly; Secure; SameSite=Lax; Path=/
Max-Age: 2592000 (30 days)
The __Host- prefix enforces Path=/; Secure at the browser level — no subdomain can set or override it.
Sessions are rolling: if a session is accessed after not being used for 24 hours and has fewer than 7 days remaining, the server issues a fresh token transparently. Most users never see an expiry prompt.
Checking the current session
const res = await fetch('/api/auth/me', { credentials: 'include' });
if (res.ok) {
const { user } = await res.json();
// user: { id, email, display_name, plan, avatar_url, wallet_address, sid }
}
There are two distinct signed-out shapes, and a client that checks only one of them will get it wrong:
| Situation | Status | Body |
|---|---|---|
| No session cookie at all | 200 |
{"user":null} |
| Cookie present but expired or revoked | 401 |
{"error":"invalid_session"} |
So treat "signed out" as !response.ok || !body.user, not as response.status === 401.
Logging out
await fetch('/api/auth/logout', {
method: 'POST',
credentials: 'include',
});
This revokes the current session in the database and clears the session cookie. The user must sign in again on all devices that were using this session.
To revoke all sessions for the current user (e.g. after a suspected account compromise):
await fetch('/api/auth/logout-everywhere', {
method: 'POST',
credentials: 'include',
});
Resetting a password
Password accounts recover through POST /api/auth/forgot-password { email }, which always answers 200 { success: true } (so it never reveals whether an address has an account) and emails a /reset-password?token=... link valid for 60 minutes. The reset page posts POST /api/auth/reset-password { token, password }. The token is checked and consumed in a single statement, so one link resets the password exactly once even under concurrent submits; a used or expired link answers 400 invalid_token. A successful reset revokes every browser session and every OAuth refresh token on the account, the same sweep logout-everywhere performs, because a reset is how an owner takes back a compromised account.
Deleting the account
DELETE /api/auth/me closes an account for good. It is the endpoint behind the
Danger Zone on /settings, and it has three gates:
a live session, a single-use CSRF token, and the literal confirmation phrase in
the body (case-insensitive). Miss the phrase and it answers
400 confirmation_required without writing anything.
import { apiFetch } from '/src/api.js'; // attaches the x-csrf-token for you
const res = await apiFetch('/api/auth/me', {
method: 'DELETE',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ confirm: 'delete my account' }),
});
const { deleted } = await res.json(); // { avatars, agents, widgets } counts
What it does, in order: retires the account's avatars, agent identities, and
embed widgets (so nothing of theirs keeps serving publicly), marks the user
row deleted, releases the /u/<username> handle back to the pool, revokes
every session and OAuth refresh token, and clears the session cookie. The row
itself is kept, which is what lets every sign-in path answer honestly
afterwards: password login fails as if the account never existed, and the
wallet/SAML paths return account_deleted rather than minting a fresh account
for the same wallet. The deletion is recorded in the audit log with the
released username, so support can restore a handle on an appeal.
Coin-community sessions (Town, /play worlds)
The coin-community surfaces (Town posting, holder passes, world gates) ride a
separate session from the main site: an X-OAuth sign-in against the
CoinCommunities upstream, kept in two httpOnly cookies scoped to
Path=/api/community so page scripts never see them:
| Cookie | Lifetime | Role |
|---|---|---|
cc_at |
1 hour | Access token (a JWT) |
cc_rt |
30 days | Refresh token |
Expiry is handled transparently: every authenticated community endpoint runs
through withAuthRefresh() (api/_lib/coin-communities.js),
which exchanges cc_rt for a fresh access token and re-sets both cookies on the
response. It fires on both ways a session goes stale:
- The
cc_atcookie is gone. This is the ordinary case an hour after sign-in, since the cookie and the JWT inside it share the same 1h lifetime, so the request arrives carrying onlycc_rt. The refresh runs first and the call proceeds on the new token. - The cookie is still there but the upstream answers 401 (a revoked or early-expired JWT). The call is retried once on the refreshed token.
Handlers must therefore test "is this user signed in?" with hasUserSession(req),
which accepts either cookie, rather than userAuthHeaders(req), which only sees
cc_at and would call an hours-old but perfectly valid session a stranger.
Callers only appear signed out when the 30-day refresh token itself is missing or
expired, so an open /play tab no longer kicks you out after the first hour.
API Keys
API keys are for server-to-server access where session cookies don't apply — CI pipelines, backend integrations, CLI tools.
Key format
Keys are prefixed sk_live_ (the dashboard can also mint sk_test_ keys) and are shown exactly once at creation. They are stored as a SHA-256 hash; if you lose the key, create a new one.
Creating a key
Via the dashboard at /dashboard/api, or via the API while signed in. A cookie-authenticated create needs a CSRF token, which apiFetch attaches for you:
import { apiFetch } from '/src/api.js'; // attaches the x-csrf-token for you
const res = await apiFetch('/api/api-keys', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'My Integration',
scope: 'avatars:read avatars:write',
expires_at: '2027-01-01T00:00:00Z', // optional
}),
});
const { data } = await res.json();
// data.token = "sk_live_xxxxx": store this; it won't be shown again
A request can send preset: "connector" instead of scope. The connector
preset is the key shape for an AI agent that holds a credential unattended
(a bot secret, a schedule, a CI job): it can read, generate, and edit agent
data, but carries a marker that caps it below every spend scope for as long
as the key lives, even if the stored scope string is later edited to add one.
A bearer caller (an API key or OAuth token holding profile) can create keys
too, but only at or below its own grant, and only receives the preset's
scopes it already holds itself: requesting any scope the caller does not
hold, or holding none of them, answers 403 insufficient_scope.
Signing in from a terminal (device link)
The three-ws CLI (docs) gets an API key without a pasted secret through an RFC 8628-style device link: POST /api/cli/link { client_name, hostname, scope } returns a user_code and a verification_uri (/cli/authorize); the person opens it signed in, can narrow the scopes (money-moving ones are flagged), and approves; the CLI polls POST /api/cli/token { device_code } every 3 seconds and receives the minted key exactly once. Poll errors use the RFC 8628 codes (authorization_pending, slow_down, access_denied, expired_token), and a link expires after 10 minutes. Approval refuses every bearer principal, so a credential can never widen itself into a new one without a person pressing the button. GET /api/cli/whoami with the key as a Bearer returns the account, plan, credential, and agent wallet.
Using a key
Pass it as a Bearer token:
const res = await fetch('/api/agents', {
headers: { 'Authorization': 'Bearer sk_live_xxxxx' }
});
Available scopes
| Scope | Access |
|---|---|
avatars:read |
Read avatar data |
avatars:write |
Create and update avatars |
avatars:delete |
Delete avatars |
agents:read |
Read agent data |
agents:write |
Create and update agents |
memory:read |
Read agent memory |
memory:write |
Write agent memory |
profile |
Read/write profile data; required to manage API keys themselves |
herald:announce |
Post announcements through the Herald (POST /api/herald/announce); the scope the herald-mcp package's THREE_WS_API_KEY needs |
wallet:read |
See the agent wallet balance, history, and spending caps |
wallet:write |
Move, commit, or redirect funds from a custodial wallet (withdraw, trade, pay, hire, launch), within its caps |
services:write |
Publish paid services that earn USDC to the agent wallet |
inference |
Model calls on the OpenAI-compatible endpoint (/api/v1/chat/completions), billed to the account's credits; keys from /api/me/inference/provision carry this scope alone |
Scopes are space-separated in the scope field. Default when unspecified: avatars:read avatars:write.
A signed-in browser session carries every scope. An API key or OAuth access token carries only what it was granted, and each route checks the scope its action needs, answering 403 insufficient_scope otherwise. Notable gates: any state-changing request to a route that spends from or redirects a custodial wallet needs wallet:write (reads pass with wallet:read); pairing or editing a chat-gateway connection needs agents:write wallet:write (listing needs agents:read); the companion inbox and Knock settings need profile, plus wallet:write to move the Knock payout address; and granting a home entity standing permission refuses every bearer with 403 confirmation_requires_session, because only a person in a session can say yes.
Security: Treat API keys as passwords. Never commit them to source control. Set the minimum scope your integration actually needs. Set an
expires_aton keys that don't need to be permanent. Rotate keys after personnel changes.
Revoking a key
import { apiFetch } from '/src/api.js'; // a cookie-authenticated revoke needs the CSRF token
await apiFetch(`/api/api-keys/${keyId}`, { method: 'DELETE' });
Or revoke via the dashboard. Revocation takes effect immediately: the key will start returning 401.
OAuth 2.1 (Third-Party App Integration)
If you're building a third-party app that users authorize to access their three.ws account — similar to how OAuth works with GitHub or Google — use the OAuth 2.1 endpoints. This is distinct from API keys (which you create for yourself).
| Endpoint | Description |
|---|---|
GET /api/oauth/authorize |
Render consent screen |
POST /api/oauth/authorize |
Submit consent |
POST /api/oauth/token |
Exchange code for tokens |
POST /api/oauth/revoke |
Revoke a token |
POST /api/oauth/introspect |
Inspect a token |
POST /api/oauth/register |
Dynamic client registration (RFC 7591) |
PKCE (S256) is mandatory. The authorization server metadata is at /.well-known/oauth-authorization-server.
Native clients may register a loopback redirect on http://127.0.0.1 or http://[::1]; at authorize time any port on that address matches (RFC 8252 section 7.3), so a CLI or desktop app registers once and binds whatever port the OS hands it. localhost redirects still match their exact port.
Client authentication
Public clients (token_endpoint_auth_method: "none", the default from dynamic registration) get no secret and identify themselves with a client_id form field.
Confidential clients present their secret the same way at /api/oauth/token, /api/oauth/revoke, and /api/oauth/introspect, using whichever method they registered:
# client_secret_basic: credentials in the Authorization header, nothing in the form
curl -X POST https://three.ws/api/oauth/revoke \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "token=$REFRESH_TOKEN"
# client_secret_post: credentials in the form body
curl -X POST https://three.ws/api/oauth/revoke \
-d "client_id=$CLIENT_ID" \
-d "client_secret=$CLIENT_SECRET" \
-d "token=$REFRESH_TOKEN"
Registration returns client_secret_expires_at: 0 alongside an issued secret: three.ws secrets do not expire, so rotate one by registering a new client. It also echoes back every optional field you registered (client_uri, logo_uri, software_id, software_version), so the response is the authoritative record of what was stored (RFC 7591 section 3.2.1). Do not re-register to "fix" a field you sent; a second registration issues a second client_id.
A rejected secret returns 401 with {"error": "invalid_client"}. If you sent the credentials in the Authorization header, the response also carries a WWW-Authenticate: Basic realm="oauth", error="invalid_client" challenge, as RFC 6749 section 5.2 requires. Treat it as a permanent credential failure, not a retryable one.
Resource indicators (RFC 8707)
three.ws issues access tokens for exactly one resource, its MCP server. If you pass resource, it must name that server; anything else is rejected with invalid_target at both /api/oauth/authorize and /api/oauth/token, rather than handing you a token whose audience is something you did not ask for. A trailing slash is ignored, and omitting the parameter entirely is fine.
# The canonical value, also published as `resource` in
# /.well-known/oauth-protected-resource
curl -X POST https://three.ws/api/oauth/token \
-d "grant_type=authorization_code" \
-d "client_id=$CLIENT_ID" \
-d "code=$CODE" \
-d "redirect_uri=$REDIRECT_URI" \
-d "code_verifier=$VERIFIER" \
-d "resource=https://three.ws/api/mcp"
For most use cases, API keys are simpler. OAuth is the right choice when you're building a product where your users grant your app access to their three.ws data.
Multi-Wallet Support
A user can link multiple Ethereum addresses to one account. All linked addresses authenticate as the same user.
Linking a wallet
Linking requires the user to sign a SIWE (EIP-4361) challenge with the wallet they want to add. POST /api/auth/wallets/nonce returns the exact message to sign; sign it and submit:
// 1. Get the link message (must be signed in already; the nonce is bound to
// your session). POST with the wallet address and its chain id.
const { nonce, message } = await fetch('/api/auth/wallets/nonce', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ address: walletAddress, chainId: 8453 }),
}).then(r => r.json());
// message is a full EIP-4361 text: "three.ws wants you to sign in… Link this
// wallet to three.ws account <email> … Nonce: … Expiration Time: …"
// 2. Sign the message with the new wallet
const signature = await signer.signMessage(message);
// 3. Submit the signed message
await fetch('/api/auth/wallets', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ message, signature }),
});
(GET /api/auth/wallets/nonce also works: it returns { nonce, domain, uri } for clients that build the SIWE message themselves. Solana wallets use the parallel nonce-solana + link-solana actions with a Sign-In-With-Solana message.)
Listing linked wallets
const { wallets } = await fetch('/api/auth/wallets', {
credentials: 'include'
}).then(r => r.json());
// wallets: [{ address, chain_id, chain_type, created_at, is_primary }, ...]
Removing a wallet
Unlinking is a state-changing call, so it needs a CSRF token (one-time, from GET /api/csrf-token) in the X-CSRF-Token header:
const { token } = await fetch('/api/csrf-token', { credentials: 'include' }).then(r => r.json());
await fetch(`/api/auth/wallets/${address}`, {
method: 'DELETE',
credentials: 'include',
headers: { 'X-CSRF-Token': token },
});
You cannot remove a wallet if it is the only one linked.
Auth in Embedded Widgets
The <agent-3d> web component does not require authentication to load and display an agent. Unauthenticated users can view any public agent.
Authentication is only needed for:
- Editing an agent (the agent edit UI)
- Publishing / on-chain registration
- Writing to persistent memory (IPFS mode)
- API key-protected endpoints you've configured for your agent
For embedded widgets with read-only access, ship without any auth plumbing.
Self-Hosting: Required Environment Variables
# Session signing + key derivation — required
# Generate with: openssl rand -base64 64
JWT_SECRET=
# Active key ID (for future rotation)
JWT_KID=k1
# Canonical app origin — used to validate SIWE domain/URI
PUBLIC_APP_ORIGIN=https://yourdomain.com
# Database
DATABASE_URL=postgresql://...
# Privy (optional — needed only if you want social/email login)
VITE_PRIVY_APP_ID=
PRIVY_APP_ID=
# Google sign-in (optional; see "Sign in with Google" above)
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=
# WalletConnect (optional — needed only for mobile wallet QR flow)
VITE_WALLETCONNECT_PROJECT_ID=
JWT_SECRET is critical. It signs all session tokens and is used (via HKDF) to derive the AES-256-GCM key that encrypts agent wallet private keys. Generate it with
openssl rand -base64 64. Never commit it. Rotate it by appending to the key set — never remove the old key while active sessions exist.
Password hashing cost is configurable via PASSWORD_ROUNDS (default: 11 bcrypt rounds).
Related
- API reference: every endpoint, including the auth routes above
- ERC-8004 identity: what a connected wallet unlocks on-chain
- Embedding guide: embeds work unauthenticated; auth is only for editing and publishing
- Architecture overview: where sessions and the API server fit
Runnable example
examples/wallet-sign-in/ The complete Sign-In with Solana and Sign-In with Ethereum round trips, run against the live auth API.
It is part of the curated set npm run export:satellites publishes as the public
three.ws examples repo, so it is installed, run, and link-checked before every release.