Docs
Contents

Project Overview

A project (Project) is the independent isolation boundary for all application backend resources and AI-native capabilities in Agentbase 2.10.0. Business databases, object storage buckets, cloud functions, messaging channels, content moderation policies, as well as large model provider credentials, AI gateway, enterprise knowledge base, intervention lexicon, long-term memory, and agent workspace configurations, all strictly belong to a specific Project. This chapter comprehensively describes project creation and context boundaries, client platform registration (Platforms, supporting 15 client types), and the full lifecycle management of server-side access keys (API Keys and Dev Keys).

Project overview page (reusing registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

Feature Overview

Taking the enterprise production template "Enterprise Intelligent Customer Service and Knowledge Hub" (Project ID: enterprise-ai-hub-210, belonging organization: Agentbase 企业智能中台 69c6d1aa00062e6bb60) as an example, when a team enters a project Console, the first screen is the Overview page. This module carries three core responsibilities:

  1. Real-time insight into project operating watermarks: The first-screen dashboard centrally presents the current project's Requests (API request throughput), Bandwidth (network bandwidth consumption), Databases (database document/row counts and read-write trends), Storage (storage bucket usage), Auth (registered end-user count), and Realtime connections (concurrent realtime long connections) within the selected time window.

  2. Client platform origin whitelist governance (Platforms): Register legitimate Hostname, Android Package name, or Apple Bundle ID for web browser applications (React / Vue / Next.js / SvelteKit, etc.), mobile native applications (iOS / Android), and cross-platform frameworks (Flutter / React Native / Unity). Any client SDK request from an unregistered origin is security-intercepted at the gateway layer.

  3. Server-side API Keys and development environment Dev Keys issuance governance:

    • API Key (standard_ prefix): For production environment backend microservices, scheduled tasks, and external Agent orchestrators; implements least-privilege authorization via the 12 major category Scope permission selector, supporting expiration time settings, Secret masking protection, and smooth rotation.

    • Dev Key (X-Appwrite-Dev-Key): For local development and integration debugging; temporarily exempts request rate limits (Ratelimit) and browser CORS cross-origin interception within a maximum validity of 30 days, and returns detailed diagnostic stacks.

Submodule nameConsole route suffixApplicable invocation planeRequired write permission Scope / role
Overview real-time dashboard/overviewControl plane visual monitoringReadable by any project member (including billing / analyst)
Platforms (platform registration)/overview/platformsClient access plane (Web SDK / mobile SDK)platforms.write (organization roles owner / admin / developer / editor)
API keys (production keys)/overview/api-keys · .../api-keys/{keyId}Server access plane (Server SDK / REST API / Agent Runtime)keys.write (Secret reading forcibly protected by server-side visibility boundary)
Dev keys (development keys)/overview/dev-keys · .../dev-keys/{keyId}Local development debugging environment (bypasses CORS and rate limits)keys.write (validity forcibly limited to 1 / 7 / 30 days)
Legacy getting-started route/get-startedRedirects to /overview/platforms; continue on the platform registration pageReadable by any project member

Core Concepts and Architecture

Inside a project's enterprise-ai-hub-210, the project context (region, table schema, service switches) together with the three integration configurations in the Integrations area (Platforms, API Keys, Dev Keys) form the access control gateway for data plane traffic:

Project Overview: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

Table of the project's four core context attributes

Context attributeConfiguration timing and modification locationGlobal impact on resources within the project
Project ID ($id) and nameSpecified when creating the project $id (e.g., enterprise-ai-hub-210); the name can be changed in Settings$id Once created, it cannot be changed; all SDK initialization and REST requests must carry this identifier via X-Appwrite-Project: enterprise-ai-hub-210.
Physical region (Region)Selected when creating a project via; determines the physical compute and storage cluster location for databases, buckets, cloud functions, and knowledge base indexes under that project.
Project table mode (Table Mode)Initialized at creation time; can be converted in Settings → Project Table ModeDetermines whether business data uses shared tables, exclusive tables, deeply exclusive tables, or the OceanBase Shared V2 mode; among these, the AI Memory long-term memory service requires the Shared V2 mode.
Service switches (Services)Settings → Overview → ServicesControls client SDK reachability for each service item by item; note thatthe unified AI Gateway (AI Gateway) is disabled by default, and the entry only appears in the left sidebar after enabling it here.

Roles, Entry Points, and Relationships

1. Console Navigation Entries and Permission Requirements

  1. Enter the project overview: select the organization Agentbase 企业智能中台 in the top navigation, click the project 企业智能客服与知识中台, and the project root redirects to /console/project-{region}-{project}/overview/platforms. Use the actual region and project identifier; Figure 1 is a historical interface reference.

  2. Switch among the three Integrations tabs: in the Integrations area in the lower half of the project overview page, you can click the Platforms, API keys, or Dev keys tabs to switch management views directly.

  3. Server-side read security boundary for the API Key Secret:

    • When reading the plaintext secret of an API Key via the Console or the management API, the server enforces a strict identity boundary check: only the owner of the organization the project belongs to, the creator of that API Key, and platform privileged members can read the full secret.

    • When other members query the Key list or details via the API, the server automatically blanks the secret field to prevent lateral privilege escalation and theft of production keys.

2. Core Positioning Comparison of API Keys and Dev Keys

Comparison dimensionProduction API Key (API keys)Development debugging key (Dev keys)
Design positioningDedicated to production and staging server-side use: allows backend services, cloud functions, and external agents to securely call project APIsLocal development environment only: helps frontend developers bypass platform rate limiting and browser CORS errors during local debugging
Request header nameX-Appwrite-Key: standard_<secret>X-Appwrite-Dev-Key: <secret>
Permission scope (Scopes)Fine-grained control: select Scopes as needed from 12 major categories at creation time; bypasses row-level ACLNo Scope concept: grants no additional data read/write permissions; only exempts CORS/Ratelimit and enables detailed error logging
Optional validity periodNever (never expires) / 7 Days / 30 days / 90 days / 1 Year / Custom DateForced short-term: only 1 Day / 7 Days / 30 Days are allowed (creating a permanently valid Dev Key is strictly forbidden)
Production red lineNever hardcode into frontend browser/mobile codeStrictly forbidden in production environments (otherwise rate limiting and cross-origin protection are lost)

Feature Details and Operation Guide

1. Registering and Managing Client Platforms

When your enterprise intelligent customer service frontend (Web portal, iOS/Android clients, or Flutter cross-platform apps) accesses Agentbase directly through the client SDK, the gateway verifies whether the request's Origin (Web) or app package name has been registered in Platforms.

Step 1: Open the platform creation wizard

  1. In the project's Overview → Integrations area, stay on the Platforms tab (path /overview/platforms).

  2. Click the Add platform button on the right and select the client platform type from the dropdown menu (backend APIs correspond to POST /v1/projects/{projectId}/platforms). The system supports a whitelist of 15 granular platform types in total.

Step 2: Fill in identifier fields by platform type

Platform categoryGranular platform type identifiers (type whitelist)Required fields and server-side validation constraintsProduction configuration examples and how to obtain them
Web appwebName (≤128 characters) + Hostname (a valid hostname or wildcard domain)Name: 企业客服 Web 门户; Hostname: support.enterprise.example.com (use localhost for local development). The wizard supports selecting React / Next.js / Vue / Nuxt / Svelte / Angular to generate initialization code.
Android nativeandroidName (≤128 characters) + Package name (key ≤256 characters) + optional storeThe Package name must exactly match the applicationId in the Android project's app/build.gradle (e.g., com.enterprise.aihub).
Apple nativeapple-ios · apple-macos · apple-watchos · apple-tvosName (≤128 characters) + Bundle ID (key ≤256 characters) + optional storeRegister separately for each target Apple device OS; the Bundle ID comes from the main Target in Xcode → General → Identity → Bundle Identifier.
Flutter cross-platformflutter-web · flutter-android · flutter-ios · flutter-linux · flutter-macos · flutter-windowsRegister separately for each target compilation platform: fill in Hostname for Web and Package name / Bundle ID for the othersIf one Flutter codebase is released simultaneously on Web, iOS, and Android, you must add 3 platform records of the corresponding types under Platforms.
React Nativereact-native-android · react-native-iosAndroid uses Package name; iOS uses Bundle IDCorresponding to the package identifiers in android/app/build.gradle and ios/*.xcodeproj respectively.
Unity engineunityName + the target platform's Package name / Bundle IDUsed for client access to 3D digital human customer service or interactive terminal applications.

Step 3: Modify and delete registered platforms

2. Creating and Managing Server-side API Keys (Including Details of 12 Major Scope Categories)

Project API Keys page (reusing the registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

Step 1: Create an API Key and configure its validity period

  1. In the Overview → Integrations area, click to switch to the API keys tab (path /overview/api-keys, as shown in Figure 2), and click Create API key in the upper right corner.

  2. Fill in the Configuration area:

    • Name (required): enter a clear usage identifier (up to 128 characters, e.g., cs-backend-prod-key or kb-ingestion-worker-key).

    • Expiration (validity period): supports selecting Never, 7 Days, 30 days, 90 days, 1 Year, or Custom Date (custom date, earliest the next day). For production environments, setting 90 days or 1 Year combined with a regular rotation policy is recommended.

Step 2: Select Scopes from 12 Major Categories Following the Principle of Least Privilege

The Scopes area of the creation wizard divides all platform permissions into 12 collapsible category panels, supporting one-click Select all / Deselect all or fine-grained selection by category:

NumberScope category panel nameExamples of core permission identifiers coveredTypical applicable business scenarios
1Authusers.read · users.write · teams.read · teams.write · sessions.writeBackend synchronization of enterprise employee accounts, management of customer service agent teams, forced logout of abnormal user sessions
2Databasedatabases.read/write · tables.read/write · columns.read/write · indexes.read/write · rows.read/write (and cloud backup policies.* / archives.* / restorations.*)Backend microservices reading and writing the enterprise_biz_db database and customer_tickets support ticket tables (when the new-style tables/columns/rows Scope is selected, the system automatically includes the legacy collections/attributes/documents compatibility variant)
3Functionsfunctions.read · functions.write · execution.read · execution.writeTriggering asynchronous cloud functions, uploading Java 17 JAR deployment packages, and querying function execution records by path
4MemoryScopes related to memory service read/write, user profiles, experience/skill distillation, and Pipeline managementBackend agent orchestrators writing multi-turn conversation memory, retrieving user profiles, and executing context compression
5Storagebuckets.read · buckets.write · files.read · files.writeManaging kb_enterprise_docs and agent_multimedia_bucket buckets and uploading/downloading files
6Messagingmessages.read/write · topics.read/write · subscribers.read/write · providers.read/writeAutomatically triggering email, SMS, or App Push notifications during backend support ticket workflow
7Sitessites.read · sites.write · deployments.read/writeCI/CD pipelines automatically triggering frontend site build deployments and one-click rollbacks
8AI GatewayScopes for the unified AI gateway, logical model routing, safety guardrails, and cache policy managementAutomating configuration of and calls to the prod-enterprise-ai-gateway gateway plane
9Knowledge BaseScopes for knowledge base, document ingestion, lexicon, hybrid retrieval, and advanced index constructionAutomatically syncing enterprise Wiki documents to the kb_enterprise_support and performing retrieval augmentation
10ObservabilityTrace/Observation queries, evaluation tasks (including knowledge index quality assessment), Prompt parsing and dataset ScopeAutomatically trigger RAG parsing evaluation and GraphRAG/Wiki index quality assessment via CI quality gates
11Trace LogsProject-level trace log query ScopeOps automation scripts pull trace logs of anomalous requests
12Otherhealth.read · locale.read · avatars.read and other general auxiliary permissionsMonitor system call health checks, region dictionaries, and avatar services

Step 3: Copy, View, and Smoothly Rotate API Keys

  1. After clicking Create, the page automatically redirects to the Key's detail page (/overview/api-keys/{keyId}), where a notification bar appears at the top offering Copy API key (copy the full Secret starting with standard_) and Copy endpoint (copy the current region's API endpoint, e.g. https://appbuild.oceanbase.com/v1).

  2. Routine inspection and status monitoring:

    • In the API keys list, you can view each key's Last accessed (shown as never if never called) and Expiration date.

    • When fewer than 14 days remain before expiration, the interface automatically highlights the Expires soon warning badge; once expired, Expired is displayed and all calls are rejected immediately.

  3. Standard zero-downtime rotation workflow (Key Rotation) in production:

    • Step One: On the API keys tab, click Create API key, select exactly the same Scopes as the old Key, and generate the new Key cs-backend-prod-key-v2.

    • Step Two: Update the new Key Secret in your enterprise configuration center or Kubernetes Secret, and roll-restart the application services.

    • Step Three: Once the old Key's Last accessed time stops changing and the new Key's Last accessed refreshes normally, go to the bottom of the old Key's detail page and click Delete API key (or select batch delete on the list page) to fully revoke the old key.

3. Creating and Using Development Environment Dev Keys

  1. In the Overview → Integrations area, click the Dev keys tab (path /overview/dev-keys), then click Create dev key.

  2. In the dialog, enter a Name (e.g. local-frontend-debug), select 1 Day, 7 Days or 30 Days in the validity period dropdown, and click Create.

  3. Copy the generated Dev Key Secret and attach the HTTP header X-Appwrite-Dev-Key: <DEV_KEY> to requests in your local development environment (or pass it via the client SDK's setDevKey() method), so you can avoid the hassle of frequently modifying the CORS domain whitelist and triggering rate limits during local debugging.

FAQ and Troubleshooting

Q1: Why does the Secret field appear empty or fail to copy when I open the detail page of an API Key created by a colleague in the Console?

Cause and troubleshooting steps: This is the key visibility security boundary enforced by the Agentbase server side: to prevent ordinary collaborating members from exporting production credentials they are not responsible for, the server specifies that only the Owner of the organization that owns the project, the creator of that API Key themselves, and platform privileged administrators can read the secret plaintext; when other members query it, the server blanks the secret in the response layer. If you need to integrate with a service, please use your own account (with keys.write permission) to create a dedicated minimal-privilege API Key; never share the same key across multiple people.

Q2: After deploying the frontend web app to a new domain, API calls report a CORS cross-origin error or 401, but it works fine locally with localhost?

Cause and troubleshooting steps: This is because previously only localhost was registered in Overview → Integrations → Platforms (or locally you used Dev Key to bypass CORS validation), while the new production/staging domain has not yet been registered. Please go to the Platforms tab, click Add platform → Web app, and add the newly launched full business domain (Hostname, without the https:// protocol prefix and path suffix, e.g. chat.enterprise.example.com) to the whitelist. After saving, frontend cross-origin requests are allowed immediately.

Q3: My legacy code uses outdated permission concepts like collections.read or documents.write, but I can't find them in the Scopes panel when creating a new API Key?

Cause and troubleshooting steps: The Agentbase 2.10.0 Console uniformly adopts relational and tabular terminology (tables.*, columns.*, rows.*), and legacy prefixes (collections.*, attributes.*, documents.*) are not listed separately in UI selectors. You only need to check the corresponding new-style Scopes such as tables.read, columns.read, and rows.write under the Database category; when the Console submits the save to the server, it automatically attaches the corresponding legacy-compatible Scope variants at the underlying layer, so legacy SDK and REST API calls are completely unaffected.