Permission String Grammar
Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.
This document defines the complete grammar of Agentbase resource-level access control (ACL) permission strings, as well as their evaluation semantics on resources such as structured tables/rows (TablesDB), document collections/documents (DocumentsDB), buckets/files (Storage), knowledge bases (KnowledgeBases), and lexicons (Lexicons).
Service and resource boundaries
Permission strings are the core declarative mechanism by which the Agentbase platform implements multi-tenant, multi-role fine-grained data isolation:
Declaration locations: They appear in the container-level
$permissionsandpermissionsparameters of tables/collections/buckets, and in the resource-level$permissionsandpermissionsparameters of rows/documents/files/knowledge bases/lexicons.Dual-gate model (container-level + resource-level): When the fine-grained security switch is enabled on a container (
rowSecurity=trueon tables,documentSecurity=trueon collections,fileSecurity=trueon buckets), access by end users (Session / JWT) is evaluated as "container-level permission OR resource-level permission"—if the container level allows, it applies to all child resources within the container; if the container level does not allow, the$permissionsof each child resource is checked individually.Anti-enumeration privacy protection boundary: For rows, documents, files, or lexicons that an end user is not authorized to read (lacking the
readpermission), the platform uniformly returns404 Not Found(or silently filters them out of list queries) and never returns403 Forbidden, preventing attackers from probing for the existence of sensitive business records via status code differences.
Resources and Base Paths
Base URL:
https://appbuild-sit.oceanbase.com/v1(orhttps://<your-endpoint>/v1).Carrying path scope: Permission strings do not correspond to a single standalone endpoint; instead, as the array field
permissions: string[], they run through the create and update request bodies of/v1/tablesdb/*,/v1/documentsdb/*,/v1/databases/*,/v1/storage/*,/v1/knowledgebases/*, and/v1/lexicons/*.Core field model:
| Field name | Direction | Type | Constraints | Description |
|---|---|---|---|---|
permissions | Request body / form | string[] | At most 100 entries per resource (some containers support higher limits) | Array of resource-level or container-level permission strings being passed in; when omitted, the default or existing permissions are retained |
$permissions | Response body | string[] | Read-only system attribute | Array of permission strings persisted after server-side normalized validation |
rowSecurity | Table configuration | boolean | Default false | When set to true, enables row-level $permissions independent authorization |
documentSecurity | Collection configuration | boolean | Default false | When set to true, enables document-level $permissions independent authorization |
fileSecurity | Bucket configuration | boolean | Default false | When set to true, enables file-level $permissions independent authorization |
Authentication and Permissions
Relationship Between Server-Side Access and Resource-Level Permissions
Server-side API Key role (Bypass ACL): Requests carrying a project API Key (
X-Appwrite-Key) execute with a server-side privileged role; only API Key Scope checks are performed (e.g.,rows.read,files.write), with no resource-level$permissionschecks. As long as the Key has the corresponding Scope, it can read and write all rows or files under the project.End-user identity (Enforce ACL): Requests carrying a user Session Cookie,
X-Appwrite-Session, orX-Appwrite-JWTare strictly evaluated by intersecting the current logged-in user's role set (any,users,user:<id>,team:<id>,team:<id>/<role>,member:<id>,label:<name>) with the target resource's$permissions; access is granted only if the intersection is non-empty.Privilege escalation grant protection (Grant Validation): When a non-server-privileged identity (e.g., a regular user creating rows or lexicons via the client) attempts to explicitly pass a
permissionsarray, the server verifies whether the caller itself holds the roles being granted (e.g., a regular user cannot grant themselves theteam:otherpermission on a row they created if they do not belong to it).
Grammar
A valid permission string consists of 动作("角色") (role identifiers must be wrapped in English double quotes):
read("any")
write("user:user_zhangwei_001")
create("label:admin")
update("team:team_tier2_support")
delete("team:team_tier2_support/owner")Action set (generated by the Permission utility class in each language SDK):
| Action | Applicable level | Semantic description |
|---|---|---|
read | Container-level & resource-level | Allows reading a single resource's details or retrieving it in a list |
create | Container-level only (tables/collections/buckets) | Allows creating new rows, new documents, or uploading new files under the parent container; meaningless for a single child resource itself |
update | Container-level & resource-level | Allows modifying business fields or metadata of an existing resource (including atomic increment/decrement operations) |
delete | Container-level & resource-level | Allows deleting an existing resource |
write | Container-level & resource-level | Aggregate write alias (equivalent to create + update + delete at container level, and update + delete at resource level); never mix write with fine-grained write actions for the same role |
Role set (generated by the Role utility class in each language SDK):
| Role string syntax | Match target and semantic description |
|---|---|
any | Any requester (covering both logged-in users and unauthenticated anonymous visitors) |
guests | Only unauthenticated anonymous visitors (requests without a Session; note: logged-in users do not match guests) |
users | Any logged-in user (including regular account logins and anonymous session logins) |
users/verified | Any logged-in user who has completed email or phone verification (emailVerification=true or phoneVerification=true) |
users/unverified | Any logged-in user who has not yet completed verification |
user:<userId> | A specified user ID (e.g., user:user_zhangwei_001) |
user:<userId>/verified | A specified user ID and the account must be in a verified state |
user:<userId>/unverified | A specified user ID and the account is in an unverified state |
team:<teamId> | All full members of a specified team (e.g., team:team_tier2_support) |
team:<teamId>/<role> | Members of a specified team who hold a specific role (e.g., team:team_tier2_support/owner) |
member:<membershipId> | A specified team membership record ID (remains valid as long as the membership exists, even if the member's role changes) |
label:<name> | All users with the specified user labels (e.g., label:vip, label:support_agent); labels are maintained via the Users API's PUT /v1/users/{userId}/labels |
Semantics on Each Resource
Row-Level and Table-Level (TablesDB)
Table resources carry the
$permissionsandrowSecurityswitches; row resources carry their own$permissions.rowSecurity=false: Row access is determined entirely by the table-level$permissions, and the$permissionson rows is ignored.rowSecurity=true: When reading/modifying/deleting rows, table-level permissions are checked first; if the table level does not allow, the row-level$permissionsis checked next; when writing, row-level permissions can be set via thepermissionsparameter (ifpermissionsis not passed when a server-side API Key creates a row, the new row's$permissionsis an empty array[], accessible only to the server-side API Key).
Collections and Documents (DocumentsDB / Legacy Databases)
Collections (
/documentsdb/*and/databases/*) use isomorphic semantics: collection$permissions+documentSecurityswitch, document$permissions.documentSecurityfor documents is fully equivalent torowSecurityfor rows; atomic increment/decrement endpoints (increment/decrement) are checked againstupdatepermissions.
Buckets and Files (Storage)
Buckets carry the
$permissionsandfileSecurityswitches; files carry$permissions.When
fileSecurity=true, file preview (/preview), view (/view), and download (/download) must match thereadpermission at the bucket level or file level, or the URL query string must include a valid file short-lived access token (?token=<secret>).
Knowledge Bases and Lexicons (KnowledgeBases & Lexicons)
Lexicons (
/v1/lexicons) support only the three actionsread,update,delete(thecreateaction is not supported), used to control different teams' maintenance permissions over synonym lexicons (e.g.,lex_enterprise_synonyms) and stopword lexicons (e.g.,lex_support_stopwords) within a project.
Endpoint overview
The following summarizes the core REST API endpoint groups that accept permissions array configuration:
| Module | Container-level permission configuration endpoint | Child resource-level permission configuration endpoint | Fine-grained security switch field |
|---|---|---|---|
| TablesDB | POST/PUT /v1/tablesdb/{databaseId}/tables* | POST/PATCH/PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows* | rowSecurity |
| DocumentsDB | POST/PUT /v1/documentsdb/{databaseId}/collections* | POST/PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents* | documentSecurity |
| Storage | POST/PUT /v1/storage/buckets* | POST/PUT /v1/storage/buckets/{bucketId}/files* | fileSecurity |
| Lexicons | — | POST/PATCH /v1/lexicons* | Resource-level permissions enabled by default |
Endpoint List
| Method + path | Permission field location | Supported action set | Purpose |
|---|---|---|---|
POST /v1/tablesdb/{databaseId}/tables | body permissions[] | read, create, update, delete, write | Create a business table and set table-level permissions and rowSecurity |
POST /v1/tablesdb/{databaseId}/tables/{tableId}/rows | body permissions[] | read, update, delete, write | Create a row record and set row-level ownership permissions |
POST /v1/storage/buckets | body permissions[] | read, create, update, delete, write | Create a bucket and set bucket-level permissions and fileSecurity |
POST /v1/storage/buckets/{bucketId}/files | formData permissions[] | read, update, delete, write | Upload a file and set file-level access policy |
POST /v1/lexicons | body permissions[] | read, update, delete | Create a project lexicon and set read/write/delete policies |
Endpoint details
Serialization Differences Between JSON Request Bodies and Multipart Forms
JSON request body (
application/json):permissionsis a standard JSON string array. Because each permission string internally contains double quotes (e.g.,read("any")), the internal double quotes must be escaped with backslashes inside JSON strings:"read(\"any\")".Multipart form (
multipart/form-data): When callingPOST /v1/storage/buckets/{bucketId}/filesto upload a file, the array parameter is passed by repeating same-namedpermissions[]form fields; in this case, no JSON outer quote escaping is needed—simply write-F 'permissions[]=read("user:user_zhangwei_001")'.
Requests and Responses
Value Examples (curl body Syntax)
The following examples use the demo project enterprise-ai-hub-210 to illustrate the complete syntax of common permission combinations in real endpoints.
Scenario 1: Create the customer service business table customer_tickets (allowing logged-in users to submit tickets, with the second-line team and ticket creators able to read and write)
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/tablesdb/enterprise_biz_db/tables" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"tableId": "customer_tickets",
"name": "企业智能客服工单表",
"rowSecurity": true,
"permissions": [
"create(\"users/verified\")",
"read(\"team:team_tier2_support\")",
"update(\"team:team_tier2_support/specialist\")",
"delete(\"team:team_tier2_support/owner\")"
]
}'
)Response example (201 Created):
{
"$id": "customer_tickets",
"$createdAt": "2026-10-22T02:00:00.000+00:00",
"$updatedAt": "2026-10-22T02:00:00.000+00:00",
"$permissions": [
"create(\"users/verified\")",
"read(\"team:team_tier2_support\")",
"update(\"team:team_tier2_support/specialist\")",
"delete(\"team:team_tier2_support/owner\")"
],
"databaseId": "enterprise_biz_db",
"name": "企业智能客服工单表",
"enabled": true,
"rowSecurity": true,
"columns": [],
"indexes": []
}Scenario 2: Create a ticket row record and grant customer user_zhangwei_001 row-level view and supplement permissions
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/tablesdb/enterprise_biz_db/tables/customer_tickets/rows" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"rowId": "TK-20261022-001",
"data": {
"title": "OceanBase 向量索引 HNSW 构建参数咨询",
"priority": "high",
"status": "open",
"customerId": "user_zhangwei_001"
},
"permissions": [
"read(\"user:user_zhangwei_001\")",
"update(\"user:user_zhangwei_001/verified\")",
"read(\"label:support_agent\")"
]
}'
)Scenario 3: Upload a ticket screenshot to agent_multimedia_bucket and set multipart/form-data file-level permissions
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/storage/buckets/agent_multimedia_bucket/files" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-F "fileId=unique()" \
-F 'permissions[]=read("user:user_zhangwei_001")' \
-F 'permissions[]=read("team:team_tier2_support")' \
-F 'permissions[]=delete("team:team_tier2_support/owner")' \
-F "file=@./ticket-attachment.png"
)Permission Combination Quick Reference Table
| Permission combination expression | Actual effective boundary |
|---|---|
read("any") | Fully public read access (including anonymous visitors and logged-in users); commonly used for public help documentation or static asset buckets |
read("users") | Readable only by logged-in sessions; unauthenticated requests return 404 |
read("guests") | Readable only by unauthenticated anonymous visitors; once a user logs in, they no longer match this rule |
read("user:u1") + read("label:vip") | Union of multiple roles: user u1 or any user with the vip label can read |
update("team:dev/owner") | Only members of the dev team whose roles membership includes owner can modify |
user:<id>/verified | Granted only after the user completes email or phone verification |
Errors and boundaries
| HTTP status code | error type (type) | trigger reason | fix and troubleshooting suggestions |
|---|---|---|---|
400 Bad Request | general_argument_invalid | The permission string is missing internal double quotes (e.g., mistakenly written as read(any)), uses an unknown action, or the role ID exceeds 36 characters | Use the SDK's Permission.read(Role.any()) builder, or write it strictly as "read(\"any\")" |
400 Bad Request | general_argument_invalid | An unsupported create(...) permission action was passed on a lexicon (/v1/lexicons) | The lexicon only supports the three permission actions read, update, and delete |
401 Unauthorized | general_access_forbidden | The client attempts to grant a role it does not itself hold (e.g., a non-team-member granting team:other) | Have the server-side API Key set cross-team permissions on the client's behalf, or only grant the current user's own roles |
404 Not Found | row_not_found / storage_file_not_found | rowSecurity=true or fileSecurity=true is enabled, but the newly created resource has an empty $permissions and is read with the client identity | Check the table/bucket fine-grained security switches and confirm that the target user's read(...) permission was passed when creating the resource |
Correspondence with the Server SDK
The Server SDKs for each language (agentbase-node-sdk@2.10.0, agentbase-python-sdk==2.10.0, etc.) include strongly typed Permission and Role builders to avoid errors from manually concatenating escaped quotes:
| Permission string literal | Node.js / TypeScript syntax | Python syntax | Related API documentation |
|---|---|---|---|
"read(\"any\")" | Permission.read(Role.any()) | Permission.read(Role.any()) | databases/overview.md |
"create(\"users/verified\")" | Permission.create(Role.users('verified')) | Permission.create(Role.users('verified')) | databases/overview.md |
"update(\"user:user_zhangwei_001\")" | Permission.update(Role.user('user_zhangwei_001')) | Permission.update(Role.user('user_zhangwei_001')) | auth/users.md |
"delete(\"team:dev/owner\")" | Permission.delete(Role.team('dev', 'owner')) | Permission.delete(Role.team('dev', 'owner')) | auth/teams.md |
"read(\"label:vip\")" | Permission.read(Role.label('vip')) | Permission.read(Role.label('vip')) | storage.md |