Web (user Session)
SDK for browser / mobile frontends: calls project features as a user Session. The Client SDK currently has only one language surface, JavaScript (Web), with npm coordinates agentbase-web-sdk@2.12.0 (installation see ../integration.md). This page covers selection, initialization, auth mounting, the error model, and the feature surface mapping; feature details live in the feature-axis docs.
How to choose among the three SDK types
| What you are writing | Which SDK | Credentials | npm package |
|---|---|---|---|
| Browser / mobile frontend; end users operatetheir owndata | Client SDK (this page) | User Session (Cookie, sent automatically) | agentbase-web-sdk |
| Node backend / Worker / CLI, reading and writing all data as the project | Server SDK (java / python / go pages of the same name also exist) | Project API Key | agentbase-node-sdk |
| Creating projects / issuing Keys / platform registration / organization and billing governance automation | Console SDK (java / python / go pages of the same name also exist) | Console Session or short-lived JWT | agentbase-console-sdk |
Only the user Session belongs in the frontend; the API Key and all secrets must stay server-side only.
Initialization: setEndpoint + setProject
import { Client, Account, TablesDB } from 'agentbase-web-sdk';
const client = new Client()
.setEndpoint('https://<host>/v1') // Environment spec see ../environment.md
.setProject('<PROJECT_ID>'); // App project ID, not 'console'
export const account = new Account(client);
export const tablesDB = new TablesDB(client);Both setters are required: endpoint determines the environment (managed SIT / production / self-hosted), project determines resource ownership and the CORS validation context.
The page origin (hostname) must already be registered under the project's Platform, otherwise
Invalid URI/ CORS 403 (see ../overview.md).Organization-related calls (project governance) additionally require
client.setOrganization(canonicalTeamId)to declare the organization header.
Get started in 5 minutes (browser)
Install:
npm install agentbase-web-sdk@2.12.0 --save-exact.Initialize with the code above and register your Web domain under the project's Overview → Platforms (otherwise CORS 403; seePlatform registration).
Register and log in to obtain a user Session:
import { ID, Query } from 'agentbase-web-sdk';
await account.create({ userId: ID.unique(), email, password, name }); // Register once only
await account.createEmailPasswordSession({ email, password });
const me = await account.get(); // Throws 401 = not logged in / session expired; handle as not logged inRead and write data as the user (subject to row-level permissions, seePermission model):
const rows = await tablesDB.listRows('app-db', 'tasks', [Query.equal('done', false)]);For complete, runnable examples of each feature, see ../examples/javascript.md.
Auth mounting (where the user Session comes from)
| Method | Mounting call | Notes |
|---|---|---|
| Email/Password | account.create() Register + account.createEmailPasswordSession() | Session lands in a Cookie and is sent automatically afterwards |
| OAuth 2.0 | account.createOAuth2Session({ provider, success, failure }) | Browser redirect; Provider / callback configuration see ../authentication.md |
| Magic URL / Phone | createMagicURLToken / createPhoneToken → createSession / updatePhoneSession | Callback page takes userId + secret |
| Anonymous | account.createAnonymousSession() | Guest identity, can be converted to a full account without data loss |
| Custom Token | Server-side users.createToken → account.createSession({ userId, secret }) | Your own account system |
| JWT (outbound) | account.createJWT() | Handed to a trusted backend for calls on its behalf; not a frontend mounting method |
Session recovery has three layers: Cookie (a_session_<projectId>) → x-appwrite-session header → x-fallback-cookies (localStorage). In cross-origin scenarios such as <img> where headers cannot be set, none of them work; use a Blob URL or File Token (../storage.md). Session management see ../profile.md.
Error model
All failures throw
AgentbaseException:codeis the HTTP status code (400 / 401 / 403 / 404 / 409 / 413 / 429…),typeis the server error type (e.g.user_unauthorized,storage_file_not_found,route_not_found), with the raw response body attached.Typical semantics:
401: not logged in / Session expired / Client SDK row-level permission violation (
hasRoleconstraint).404 under storage
fileSecuritymay mean insufficient permission rather than nonexistence—check permissions first (../storage.md).409 conflict (ID / email already exists, deletion state conflict); 413 quota exceeded; 429 rate limited.
Frontend convention: treat
account.get()failures as not-logged-in and redirect to login; do not swallow exceptions or use?? 0to mask missing data (in usage aggregation,quantity: nullmust be shown as missing).
Feature surface mapping table (client-available surface)
| Feature domain | Client SDK service | Details and boundaries |
|---|---|---|
| Account authentication (full spectrum + MFA) | Account | ../authentication.md |
| Account profile / sessions / preferences | Account | ../profile.md |
| Current account quota limits | Account.getQuotaLimits() / updateQuotaLimits() / deleteQuotaLimits() / listLimitsProjects(); account-level only, excludes project quota or /limits governance | ../limits.md |
| Database row read/write (under user Session, permission-constrained) | TablesDB / Databases (legacy doc surface) | ../databases.md, ../permissions.md |
| Query construction | Query | ../databases.md |
| Object storage (upload / download / preview URL) | Storage | ../storage.md |
| Function triggering (requires execute permission) | Functions | ../functions.md |
| Teams (your own teams and members) | Teams | ../teams.md |
| Realtime subscriptions | Realtime + Channel (Channel.tablesdb(db).table(t).row(r), Channel.files(), account channels) | Subscribe to row / file / account changes; subscribe(...) returns a handle close(); channels are constructors, not function strings |
| Organization project governance (Owner) | Projects (listInactiveByOrganization and 4 methods) | ../project-governance.md; requires Owner Session + setOrganization |
| Memory data plane | Memory | The user's own authorized memory read/write; the management plane is not on the client |
| LLM / AI data plane | LlmGateway, AiGateway, KnowledgeBases | End-user data plane subset; must not hold Gateway Keys / Provider credentials |
| Others | Avatars, Locale, Graphql | General utilities and query surface |
Client boundaries (unavailable surface)
| Unavailable | Reason / alternative |
|---|---|
User management (users.list, editing others' profiles, labels) | Management-plane only; use the Server SDK (../users.md) |
File Token issuance (Tokens) | Requires an API Key; issue short-lived links via a Function / backend |
| Platform registration / OAuth Provider configuration / API Key management | Console Session surface or management API Key (../overview.md) |
| Granting rows / files to others | Client SDK hasRole constraint; proxy through a Function (../permissions.md) |
| Organization management, billing, organization Keys | Console SDK / Console UI (../organization.md) |
| Bucket / table schema baseline configuration | Baselines are pushed from the server; the client only consumes |
Usage notes and boundaries
Do not put API Keys, JWTs, Provider Secrets, or Gateway Keys into frontend code or build variables; the frontend only holds the user Session.
When creating rows on the client, omit
permissionsto get creator default permissions;updateRowwith permissions is a full replacement (../permissions.md).Realtime and REST share the permission model: cannot subscribe = not permission-visible, not a connection problem.
Multiple environments (SIT / production) each use their own project and Platform registration; endpoint and project must belong to the same environment.
Example Guide
JavaScript (Web) complete call examples: ../examples/javascript.md