Docs
Contents

Permission String Grammar

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:

Resources and Base Paths

Field nameDirectionTypeConstraintsDescription
permissionsRequest body / formstring[]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
$permissionsResponse bodystring[]Read-only system attributeArray of permission strings persisted after server-side normalized validation
rowSecurityTable configurationbooleanDefault falseWhen set to true, enables row-level $permissions independent authorization
documentSecurityCollection configurationbooleanDefault falseWhen set to true, enables document-level $permissions independent authorization
fileSecurityBucket configurationbooleanDefault falseWhen set to true, enables file-level $permissions independent authorization

Authentication and Permissions

Relationship Between Server-Side Access and Resource-Level Permissions

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

ActionApplicable levelSemantic description
readContainer-level & resource-levelAllows reading a single resource's details or retrieving it in a list
createContainer-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
updateContainer-level & resource-levelAllows modifying business fields or metadata of an existing resource (including atomic increment/decrement operations)
deleteContainer-level & resource-levelAllows deleting an existing resource
writeContainer-level & resource-levelAggregate 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 syntaxMatch target and semantic description
anyAny requester (covering both logged-in users and unauthenticated anonymous visitors)
guestsOnly unauthenticated anonymous visitors (requests without a Session; note: logged-in users do not match guests)
usersAny logged-in user (including regular account logins and anonymous session logins)
users/verifiedAny logged-in user who has completed email or phone verification (emailVerification=true or phoneVerification=true)
users/unverifiedAny logged-in user who has not yet completed verification
user:<userId>A specified user ID (e.g., user:user_zhangwei_001)
user:<userId>/verifiedA specified user ID and the account must be in a verified state
user:<userId>/unverifiedA 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)

Collections and Documents (DocumentsDB / Legacy Databases)

Buckets and Files (Storage)

Knowledge Bases and Lexicons (KnowledgeBases & Lexicons)

Endpoint overview

The following summarizes the core REST API endpoint groups that accept permissions array configuration:

ModuleContainer-level permission configuration endpointChild resource-level permission configuration endpointFine-grained security switch field
TablesDBPOST/PUT /v1/tablesdb/{databaseId}/tables*POST/PATCH/PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows*rowSecurity
DocumentsDBPOST/PUT /v1/documentsdb/{databaseId}/collections*POST/PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents*documentSecurity
StoragePOST/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 + pathPermission field locationSupported action setPurpose
POST /v1/tablesdb/{databaseId}/tablesbody permissions[]read, create, update, delete, writeCreate a business table and set table-level permissions and rowSecurity
POST /v1/tablesdb/{databaseId}/tables/{tableId}/rowsbody permissions[]read, update, delete, writeCreate a row record and set row-level ownership permissions
POST /v1/storage/bucketsbody permissions[]read, create, update, delete, writeCreate a bucket and set bucket-level permissions and fileSecurity
POST /v1/storage/buckets/{bucketId}/filesformData permissions[]read, update, delete, writeUpload a file and set file-level access policy
POST /v1/lexiconsbody permissions[]read, update, deleteCreate a project lexicon and set read/write/delete policies

Endpoint details

Serialization Differences Between JSON Request Bodies and Multipart Forms

  1. JSON request body (application/json): permissions is 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\")".

  2. Multipart form (multipart/form-data): When calling POST /v1/storage/buckets/{bucketId}/files to upload a file, the array parameter is passed by repeating same-named permissions[] 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)

curl -X POST "https://appbuild-sit.oceanbase.com/v1/tablesdb/enterprise_biz_db/tables" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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

curl -X POST "https://appbuild-sit.oceanbase.com/v1/tablesdb/enterprise_biz_db/tables/customer_tickets/rows" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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

curl -X POST "https://appbuild-sit.oceanbase.com/v1/storage/buckets/agent_multimedia_bucket/files" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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 expressionActual 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>/verifiedGranted only after the user completes email or phone verification

Errors and boundaries

HTTP status codeerror type (type)trigger reasonfix and troubleshooting suggestions
400 Bad Requestgeneral_argument_invalidThe permission string is missing internal double quotes (e.g., mistakenly written as read(any)), uses an unknown action, or the role ID exceeds 36 charactersUse the SDK's Permission.read(Role.any()) builder, or write it strictly as "read(\"any\")"
400 Bad Requestgeneral_argument_invalidAn unsupported create(...) permission action was passed on a lexicon (/v1/lexicons)The lexicon only supports the three permission actions read, update, and delete
401 Unauthorizedgeneral_access_forbiddenThe 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 Foundrow_not_found / storage_file_not_foundrowSecurity=true or fileSecurity=true is enabled, but the newly created resource has an empty $permissions and is read with the client identityCheck 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 literalNode.js / TypeScript syntaxPython syntaxRelated 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