Docs
Contents

Project Overview

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

Usage workflow

  1. Create project: Projects.create, created within the organization, yielding a project ID and metadata; a single account can have at most 100 projects.

  2. Switch context: call client.setProject(新项目 ID) before invoking interfaces that depend on the "current project" (such as variables and usage of the Project service).

  3. 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).

  4. Project variables: the createVariable / listVariables / updateVariable / deleteVariable of the Console SDK Project service; variables in secret: true are stored encrypted, the API only returns empty values, and at runtime (functions / sites) they are read via environment variables.

  5. Server API Key: Projects.createKey({ projectId, name, scopes, keyId, expire }) (both keyId and expire are optional); secret appears only once in the creation response, so save it properly immediately. Issue with the minimal scope set (e.g., only databases.read/write + users.read/write).

  6. 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.

  7. Platform registration and CORS: register browser origins with createPlatform({ projectId, type: PlatformType.Web, name, hostname }); use listPlatforms for deduplication checking and deletePlatform for decommissioning.

  8. OAuth Provider: configure built-in Providers with updateOAuth2 (provider, appId, secret, enabled); the generic customOauth2 for 2.6.0 saves the configuration envelope through the same OAuth management entry point (prefer the Console page, avoiding manually serializing Secret/config).

  9. 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)

ParameterDescription
projectIdID.unique() or a custom ID
teamIdthe canonical Team ID of the owning organization
region2.6.0 only default is supported
poolTagOptional; 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)

RuleDescription
Registration targetthe 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 matchinglocalhost:5173 both localhost:3000 and only need localhost registered
Validation timingClient SDK requests, OAuth success/failure URLs, CORS preflight; Server SDK (API Key) is not restricted
Platform typeweb / flutter-web / apple-ios / android / react-native-*; for mobile, fill the Bundle ID / Package name into the key field
AuthenticationConsole SDK + account Session only (setCookie after login); project API Keys lack the platforms.* scope and cannot manage platforms
Consequence of not registeringInvalid 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

SDK Category Differences

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.

import { Client, Account, Projects, Teams, ID } from 'agentbase-console-sdk';

const client = new Client()
  .setEndpoint('https://appbuild.oceanbase.com/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)
});

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.

client.setProject(project.$id);   // Afterwards X-Appwrite-Project points to the new project

Authentication and session policies

Project-level authentication and session governance, with one update* method per policy.

// 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

Project 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.

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 shape

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.

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 creation

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).

// 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.

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 offline

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.

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).

const usage = await projects.listUsageAggregates({ projectId: project.$id });

Example Guide