Docs
Contents

Project Overview

A project (Project) is the independent isolation boundary for all application backend resources and AI-native capabilities in Agentbase. 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, and the full lifecycle management of server-side access keys (API Keys and Dev Keys).

Feature Overview

After entering a project, use the sidebar to open Overview. A new project may show a getting-started guide first. 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 registration (Platforms): Register a Hostname for web applications and a Package name or Bundle ID for mobile applications. Browser requests validate Origin when the relevant conditions apply. Platform registration does not replace authentication, service switches, or resource permissions.

  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 13-category Scope selector, supporting expiration time settings, Secret masking protection, and smooth rotation.

    • Dev Key (X-Appwrite-Dev-Key): For local development and debugging; it can bypass rate limits and applicable browser origin checks and provide detailed diagnostics. The Console offers 1, 7, or 30 days; the management API does not enforce a 30-day maximum. Set an expiration and revoke the key when finished.

Submodule nameConsole route suffixApplicable invocation planeRequired write permission Scope / role
Overview real-time dashboard/overviewControl plane monitoringProject read access is required; organization billing and analyst roles do not include projects.read by default
Platforms (platform registration)/overview/platformsClient platform configurationplatforms.write (owner / admin among the default organization roles)
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 debuggingdevKeys.write (owner / admin among default organization roles; Console options: 1 / 7 / 30 days)
Project guide/get-startedGuides you through project creation, platform connection, and building an appRequires project read access; configuration actions require their respective permissions

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 your organization and project in the top navigation. The project root redirects to /console/project-{region}-{project}/overview/platforms. Use the actual region and project identifier.

  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:

    • The project API key list and detail routes first check route permissions. For user identities, plaintext access also depends on project creator account, platform privilege, a server-recognized owner identity, or owner / admin membership that passes active organization and project binding checks. Creating an individual key alone is not the access condition.

    • The secret is blanked for users who do not satisfy the plaintext access checks. List and detail requests made with an API Key are also redacted. Protect accounts authorized to read secrets.

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 13 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 / 7 Days / 30 days / 90 days / 1 Year / Custom DateThe Console offers 1 Day / 7 Days / 30 Days; the management API accepts an empty expiration and does not enforce a 30-day maximum. Set a short expiration and revoke the key after use.
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

For browser-based web applications, register the frontend domain under Platforms. Applicable origin checks validate the request Origin; mobile package identifiers are platform configuration and do not imply per-request package validation. Access still requires the appropriate identity, enabled services, and resource permissions.

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 13 Scope Categories)

Project API key list

Figure: A temporary example API key in a 2.12.0 test project; the key was deleted after capture.

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), 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 13 Categories Following the Principle of Least Privilege

The Scopes area of the creation wizard divides all platform permissions into 13 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
8Modelsllm-gateway.providers.read/write · llm-gateway.keys.read/write · llm-gateway.executeManage model providers, keys, and model calls
9Tool GatewayaiGateway.read · aiGateway.write · aiGateway.executeManage and call the tool gateway
10Knowledge 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
11ObservabilityTrace/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
12Trace LogsProject-level trace log query ScopeOps automation scripts pull trace logs of anomalous requests
13Otherhealth.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: The list and detail routes check access first, then determine plaintext visibility from the project creator account, platform privilege, server-recognized owner identity, or active organization membership and project bindings. Organization owner / admin members who meet those checks can read the secret; creating an individual key is not itself the access condition. List and detail requests made with an API Key are redacted. Ask an administrator with keys.write to create a least-privilege key and protect accounts that can read it.

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: One possibility is that Overview → Integrations → Platforms contains only localhost, or local testing used a Dev Key, while the new domain is not registered. Add the web platform hostname under Platforms (without the protocol or path, for example chat.enterprise.example.com), then check the browser's actual Origin, request identity, and other permissions before retrying.

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