Project Overview
Replace <APPBASE_ENDPOINT_WITH_V1>, <APPBASE_CONSOLE_ORIGIN>, and <APPBASE_CONSOLE_HOST> where used with values for the intended environment before running the examples.
Overview and use cases
Creation and configuration of the project itself: creation (region / poolTag / legal information), authentication and session policies, project environment variables, Server API Key and Dev Key, platform registration (Platform) and CORS, OAuth Provider configuration and callback URLs. This is the first stop before integrating any business feature; for in-project resources (databases, storage, functions, etc.), see the other documents under project/.
Prerequisites
A Console account with project creation permission; the organization (Team) already exists, see organization.md.
Console SDK (
agentbase-console-sdk@2.8.0) initialization:setEndpoint+setProject('console')(or the actual Console project ID of the environment), authenticated with an email/password Session or short-lived JWT.For endpoint / region environment facts, see environment.md.
Usage workflow
Create project:
Projects.create, created within the organization, yielding a project ID and metadata; a single account can have at most 100 projects.Switch context: call
client.setProject(新项目 ID)before invoking interfaces that depend on the "current project" (such as variables and usage of theProjectservice).Authentication and session policies:
updateAuthDuration(Session validity, in seconds),updateAuthLimit(login attempt rate limiting),updateAuthSessionsLimit(sessions per user),updateAuthPasswordDictionary/updateAuthPasswordHistory(password policies),updateSessionAlerts/updateSessionInvalidation(session reminders and invalidation).Project variables: the
createVariable/listVariables/updateVariable/deleteVariableof the Console SDKProjectservice; variables insecret: trueare stored encrypted, the API only returns empty values, and at runtime (functions / sites) they are read via environment variables.Server API Key:
Projects.createKey({ projectId, name, scopes, keyId, expire })(bothkeyIdandexpireare optional);secretappears only once in the creation response, so save it properly immediately. Issue with the minimal scope set (e.g., onlydatabases.read/write+users.read/write).Dev Key: Keys for development and debugging (
createDevKey/listDevKeys/getDevKey/updateDevKey/deleteDevKey); semantics are parallel to API Keys, but they are intended for development-time use and must not enter production configuration.Platform registration and CORS: register browser origins with
createPlatform({ projectId, type: PlatformType.Web, name, hostname }); uselistPlatformsfor deduplication checking anddeletePlatformfor decommissioning.OAuth Provider: configure built-in Providers with
updateOAuth2(provider,appId,secret,enabled); the genericcustomOauth2for 2.6.0 saves the configuration envelope through the same OAuth management entry point (prefer the Console page, avoiding manually serializing Secret/config).Project usage (2.6.0):
projects.listUsageAggregates({ projectId })reads the most recent 30 UTC-day aggregates at the project dimension.
Key parameters and returns
Create Project
create({ projectId, name, teamId, region, poolTag, description, logo, url, legalName, legalCountry, legalState, legalCity, legalAddress, legalTaxId }) (region, poolTag, description, logo, url, legalName, legalCountry, legalState, legalCity, legalAddress, legalTaxId are all optional)
| Parameter | Description |
|---|---|
projectId | ID.unique() or a custom ID |
teamId | the canonical Team ID of the owning organization |
region | 2.6.0 only default is supported |
poolTag | Optional; database pool tag; when omitted, matches the fallback (empty tag) pool; available tags confirmed per environment |
Returns Models.Project (containing metadata such as $id, teamId, region, authDatabasesStorageLimit).
Platform Registration (Determines CORS and OAuth Callback Validity)
| Rule | Description |
|---|---|
| Registration target | the hostname from the browser address bar (e.g., localhost, 127.0.0.1, 11.124.5.7, app.example.com), not the API endpoint, and without protocol / port / path |
| Ports do not participate in matching | localhost:5173 both localhost:3000 and only need localhost registered |
| Validation timing | Client SDK requests, OAuth success/failure URLs, CORS preflight; Server SDK (API Key) is not restricted |
| Platform type | web / flutter-web / apple-ios / android / react-native-*; for mobile, fill the Bundle ID / Package name into the key field |
| Authentication | Console SDK + account Session only (setCookie after login); project API Keys lack the platforms.* scope and cannot manage platforms |
| Consequence of not registering | Invalid URI, OAuth failures, CORS 403 |
OAuth Callback URLs
{endpoint}/account/sessions/oauth2/callback/{provider}/{projectId}{provider} lowercase; fill this URL into the application configuration of the upstream Provider (GitHub / Google, etc.). success/failure must fall under the origin of an already registered Platform.
Errors and boundaries
Project creation overrun: 100 project limit per account; count-based quota overruns have distinct error types.
Passing a non-
defaultvalue toregionfails directly with 400 (Value must be one of (default)).With only
createEmailPasswordSessionand nosetCookie,createPlatformreports missing scopes as a guests identity; project API Keys calling platform interfaces likewise fail.API Key
secret: once lost, it cannot be retrieved again; you can only delete and recreate. When rotating, create the new Key first, then revoke the old Key.For the semantics and security boundaries after OAuth Provider changes (including customOauth2 configuration), see authentication.md.
quota / ratelimit (
updateQuotaLimitsand the comprehensive/limits) belong to limit governance; for model details seeskills/ob-agentbase/references/console-sdk.md, not expanded here.
SDK Category Differences
Console SDK (JS): the main body of this page (project CRUD, Key/Dev Key, platforms, OAuth, authentication policies, variables, usage aggregation).
Console Java SDK: the
Projects/Projectservices mirror the JS shape (createwith region/poolTag,createKey,createPlatform,updateAuth*, variables, etc.); proprietary services without a JS Console SDK counterpart (e.g.,Sql).Server SDK: contains no project management surface (project creation / platform registration / OAuth configuration are all outside the Server SDK scope); it consumes the API Keys issued here.
Client SDK: a pure consumer; it depends on platform registration on this page to work, see client-sdk/web.md.
Examples by language
The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).
Create Project
Create a project within an organization to get a project ID and metadata; a single account can have at most 100 projects. region 2.6.0 only supports default; poolTag optionally specifies the database pool.
- Console (Node.js)
- Java
import { Client, Account, Projects, Teams, ID } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID); // Console's own project id
const account = new Account(client);
await account.createEmailPasswordSession({ email: '...', password: '...' }); // or client.setJWT(token)
const teams = new Teams(client);
const team = await teams.create({ teamId: ID.unique(), name: 'My Team' });
const projects = new Projects(client);
const project = await projects.create({
projectId: ID.unique(),
name: 'todo-app',
teamId: team.$id, // Console page Organization = Team
region: 'default',
// poolTag: 'pool-a', // optional: database pool tag (SDK >= 1.13.2)
});import io.agentbase.console.ID;
import io.agentbase.console.services.Projects;
import java.util.List;
Projects projects = new Projects(client);
var list = projects.list(List.of(Query.limit(20)), null, null);
// Created as positional arguments (projectId, name, teamId, …); pass null for optional parameters;
// poolTag specifies the database pool (Agentbase extension). See io.agentbase.console.services.Projects for the full signature
var project = projects.create(
ID.unique(), // projectId
"billing-service", // name
null // teamId
);
projects.get(project.getId());
projects.delete(project.getId());Switching project context
After creating or operating on other projects, switch the "current project" first before calling APIs that depend on it (variables of the Project service, usage, etc.); this is SDK-side context switching with no REST equivalent.
- Console (Node.js)
client.setProject(project.$id); // Afterwards X-Appwrite-Project points to the new projectAuthentication and session policies
Project-level authentication and session governance, with one update* method per policy.
- Console (Node.js)
- Java
// Fill each method's request body per policy semantics (values/switches); see agentbase-console-sdk type definitions for the shape
await projects.updateAuthDuration({ projectId: project.$id }); // Session validity period (seconds)
await projects.updateAuthLimit({ projectId: project.$id }); // Login attempt rate limiting
await projects.updateAuthSessionsLimit({ projectId: project.$id }); // Number of sessions per user
await projects.updateAuthPasswordDictionary({ projectId: project.$id }); // Password dictionary validation
await projects.updateAuthPasswordHistory({ projectId: project.$id }); // Password history
await projects.updateSessionAlerts({ projectId: project.$id }); // New device login alert
await projects.updateSessionInvalidation({ projectId: project.$id }); // Session invalidated// Session validity (seconds) and login rate limiting (the parameter is a Long; note the L suffix on literals)
projects.updateAuthDuration(project.getId(), 3600L);
projects.updateAuthLimit(project.getId(), 10L);
// Also available: updateAuthSessionsLimit / updateSessionAlerts / updateSessionInvalidation /
// A family of update* methods such as updateAuthPasswordDictionary / updateAuthPasswordHistoryProject variables
Environment variables injected into functions and sites at build/runtime; secret: true stored encrypted and cannot be switched back once changed; management API reads are always masked.
- Console (Node.js)
- Java
- REST (curl)
import { Project } from 'agentbase-console-sdk';
// The Project service operates on the current project set by setProject; no projectId parameter
const proj = new Project(client);
// createVariable / listVariables / updateVariable / deleteVariable;
// See agentbase-console-sdk type definitions for the shapeimport io.agentbase.console.services.Project;
import io.agentbase.console.ID;
// Applies to the current project set via setProject
new Project(client).listVariables(null, null);
new Project(client).createVariable(ID.unique(), "SMTP_HOST", "smtp.example.com", false);curl -X POST "https://<your-endpoint>/v1/project/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"variableId": "unique()",
"key": "SMTP_HOST",
"value": "smtp.example.com",
"secret": false
}'
curl "https://<your-endpoint>/v1/project/variables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"Server API Key
Issue with the minimal set of scopes; secret appears only once in the creation response, so store it safely right away. When rotating, create the new Key first, then revoke the old Key.
- Console (Node.js)
- Java
import { Scopes } from 'agentbase-console-sdk';
const key = await projects.createKey({
projectId: project.$id,
name: 'setup-script',
scopes: [
Scopes.DatabasesRead,
Scopes.DatabasesWrite,
Scopes.UsersRead,
Scopes.UsersWrite,
],
});
// key.secret is returned only once at creationvar key = projects.createKey(
project.getId(),
"ci-deploy",
List.of(Scopes.USERS_READ, Scopes.USERS_WRITE) // Choose the minimal set based on the tool's actual needs
);
projects.listKeys(project.getId(), null, null);
projects.deleteKey(project.getId(), key.getId());Dev Key
Keys for development and debugging; semantically parallel to API Keys but intended for development use, not for production configuration; method family createDevKey / listDevKeys / getDevKey / updateDevKey / deleteDevKey (exclusive to the Console SDK; for the form, see the agentbase-console-sdk type definitions).
- Console (Node.js)
// await projects.createDevKey({ projectId: project.$id, name: 'dev-sandbox' });
// await projects.listDevKeys(project.$id);Platform registration and CORS
Register the hostname from the browser address bar (excluding protocol/port/path); failure to register causes Invalid URI, OAuth failures, and CORS 403. Console SDK + account Session only (setCookie after login); project API Keys have no platforms.* scope.
- Console (Node.js)
- Java
import { PlatformType } from 'agentbase-console-sdk';
await projects.createPlatform({
projectId: project.$id,
type: PlatformType.Web,
name: 'localhost',
hostname: 'localhost', // Both localhost:5173 and localhost:3000 only require registering localhost
});
await projects.listPlatforms({ projectId: project.$id }); // Deduplication check
// await projects.deletePlatform({ projectId: project.$id, platformId }); // take offlineprojects.createPlatform(
project.getId(),
io.agentbase.console.enums.PlatformType.WEB,
"app-web",
"app.example.com" // The hostname whitelist is the CORS/callback constraint
);
projects.listPlatforms(project.getId(), null);OAuth Provider
Configure the built-in OAuth Provider (appId / secret / enabled); the {provider} in the callback URL {endpoint}/account/sessions/oauth2/callback/{provider}/{projectId} is lowercase and must be filled into the upstream Provider's application configuration.
- Console (Node.js)
import { OAuthProvider } from 'agentbase-console-sdk';
await projects.updateOAuth2({
projectId: project.$id,
provider: OAuthProvider.Github,
appId: 'your_app_id',
secret: 'your_app_secret',
enabled: true,
});Project usage
Usage aggregates for the most recent 30 UTC days at the project dimension (2.6.0 extension; quantity: null means missing — do not default it to 0).
- Console (Node.js)
- Java
const usage = await projects.listUsageAggregates({ projectId: project.$id });new Projects(client).getUsageAggregates(project.getId());Example Guide
Examples by language are consolidated in the language tree
examples/; for the complete idempotent script form of "Console login → setCookie → create Team → create project → register Platform → create Key", seeskills/ob-agentbase/references/console-sdk.mdandskills/ob-agentbase/references/platform-registration.md.