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:
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.
Client platform registration (Platforms): Register a
Hostnamefor web applications and aPackage nameorBundle IDfor mobile applications. Browser requests validateOriginwhen the relevant conditions apply. Platform registration does not replace authentication, service switches, or resource permissions.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 name | Console route suffix | Applicable invocation plane | Required write permission Scope / role |
|---|---|---|---|
| Overview real-time dashboard | /overview | Control plane monitoring | Project read access is required; organization billing and analyst roles do not include projects.read by default |
| Platforms (platform registration) | /overview/platforms | Client platform configuration | platforms.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 debugging | devKeys.write (owner / admin among default organization roles; Console options: 1 / 7 / 30 days) |
| Project guide | /get-started | Guides you through project creation, platform connection, and building an app | Requires 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:
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 attribute | Configuration timing and modification location | Global impact on resources within the project |
|---|---|---|
Project ID ($id) and name | Specified 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 Mode | Determines 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 → Services | Controls 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
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.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.
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/adminmembership that passes active organization and project binding checks. Creating an individual key alone is not the access condition.The
secretis 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 dimension | Production API Key (API keys) | Development debugging key (Dev keys) |
|---|---|---|
| Design positioning | Dedicated to production and staging server-side use: allows backend services, cloud functions, and external agents to securely call project APIs | Local development environment only: helps frontend developers bypass platform rate limiting and browser CORS errors during local debugging |
| Request header name | X-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 ACL | No Scope concept: grants no additional data read/write permissions; only exempts CORS/Ratelimit and enables detailed error logging |
| Optional validity period | Never / 7 Days / 30 days / 90 days / 1 Year / Custom Date | The 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 line | Never hardcode into frontend browser/mobile code | Strictly 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
In the project's Overview → Integrations area, stay on the Platforms tab (path
/overview/platforms).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 category | Granular platform type identifiers (type whitelist) | Required fields and server-side validation constraints | Production configuration examples and how to obtain them |
|---|---|---|---|
| Web app | web | Name (≤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 native | android | Name (≤128 characters) + Package name (key ≤256 characters) + optional store | The Package name must exactly match the applicationId in the Android project's app/build.gradle (e.g., com.enterprise.aihub). |
| Apple native | apple-ios · apple-macos · apple-watchos · apple-tvos | Name (≤128 characters) + Bundle ID (key ≤256 characters) + optional store | Register separately for each target Apple device OS; the Bundle ID comes from the main Target in Xcode → General → Identity → Bundle Identifier. |
| Flutter cross-platform | flutter-web · flutter-android · flutter-ios · flutter-linux · flutter-macos · flutter-windows | Register separately for each target compilation platform: fill in Hostname for Web and Package name / Bundle ID for the others | If one Flutter codebase is released simultaneously on Web, iOS, and Android, you must add 3 platform records of the corresponding types under Platforms. |
| React Native | react-native-android · react-native-ios | Android uses Package name; iOS uses Bundle ID | Corresponding to the package identifiers in android/app/build.gradle and ios/*.xcodeproj respectively. |
| Unity engine | unity | Name + the target platform's Package name / Bundle ID | Used for client access to 3D digital human customer service or interactive terminal applications. |
Step 3: Modify and delete registered platforms
Click any registered platform in the list to enter its detail page, where you can modify the Name, Hostname / Package name / Bundle ID, and app store ID (
store, ≤256 characters) at any time.Deletion risk warning: Removing a registered web domain can affect browser origin checks or redirect URL validation. The result depends on the route and credentials; do not rely on platform removal to block every client request. Check authentication, service switches, and resource permissions as well.
2. Creating and Managing Server-side API Keys (Including 13 Scope Categories)
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
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.Fill in the Configuration area:
Name (required): enter a clear usage identifier (up to 128 characters, e.g.,
cs-backend-prod-keyorkb-ingestion-worker-key).Expiration (validity period): supports selecting
Never,7 Days,30 days,90 days,1 Year, orCustom Date(custom date, earliest the next day). For production environments, setting90 daysor1 Yearcombined 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:
| Number | Scope category panel name | Examples of core permission identifiers covered | Typical applicable business scenarios |
|---|---|---|---|
| 1 | Auth | users.read · users.write · teams.read · teams.write · sessions.write | Backend synchronization of enterprise employee accounts, management of customer service agent teams, forced logout of abnormal user sessions |
| 2 | Database | databases.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) |
| 3 | Functions | functions.read · functions.write · execution.read · execution.write | Triggering asynchronous cloud functions, uploading Java 17 JAR deployment packages, and querying function execution records by path |
| 4 | Memory | Scopes related to memory service read/write, user profiles, experience/skill distillation, and Pipeline management | Backend agent orchestrators writing multi-turn conversation memory, retrieving user profiles, and executing context compression |
| 5 | Storage | buckets.read · buckets.write · files.read · files.write | Managing kb_enterprise_docs and agent_multimedia_bucket buckets and uploading/downloading files |
| 6 | Messaging | messages.read/write · topics.read/write · subscribers.read/write · providers.read/write | Automatically triggering email, SMS, or App Push notifications during backend support ticket workflow |
| 7 | Sites | sites.read · sites.write · deployments.read/write | CI/CD pipelines automatically triggering frontend site build deployments and one-click rollbacks |
| 8 | Models | llm-gateway.providers.read/write · llm-gateway.keys.read/write · llm-gateway.execute | Manage model providers, keys, and model calls |
| 9 | Tool Gateway | aiGateway.read · aiGateway.write · aiGateway.execute | Manage and call the tool gateway |
| 10 | Knowledge Base | Scopes for knowledge base, document ingestion, lexicon, hybrid retrieval, and advanced index construction | Automatically syncing enterprise Wiki documents to the kb_enterprise_support and performing retrieval augmentation |
| 11 | Observability | Trace/Observation queries, evaluation tasks (including knowledge index quality assessment), Prompt parsing and dataset Scope | Automatically trigger RAG parsing evaluation and GraphRAG/Wiki index quality assessment via CI quality gates |
| 12 | Trace Logs | Project-level trace log query Scope | Ops automation scripts pull trace logs of anomalous requests |
| 13 | Other | health.read · locale.read · avatars.read and other general auxiliary permissions | Monitor system call health checks, region dictionaries, and avatar services |
Step 3: Copy, View, and Smoothly Rotate API Keys
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 withstandard_) and Copy endpoint (copy the current region's API endpoint, e.g.https://appbuild.oceanbase.com/v1).Routine inspection and status monitoring:
In the API keys list, you can view each key's Last accessed (shown as
neverif never called) and Expiration date.When fewer than 14 days remain before expiration, the interface automatically highlights the
Expires soonwarning badge; once expired,Expiredis displayed and all calls are rejected immediately.
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
In the Overview → Integrations area, click the Dev keys tab (path
/overview/dev-keys), then click Create dev key.In the dialog, enter a Name (e.g.
local-frontend-debug), select1 Day,7 Daysor30 Daysin the validity period dropdown, and click Create.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'ssetDevKey()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.

