Docs
Contents

Permissions (row-level / table-level / storage and complex authorization)

Overview and use cases

Agentbase's authorization model: permission actions × roles → $permissions strings, configured separately on tables (Table), rows (Row), and buckets / files, and taking effect together with the rowSecurity / fileSecurity switches. When to use: implementing access control such as "users can only access their own data", "team sharing", "admin visibility"; as well as complex scenarios where authorization must be granted to others under Client SDK constraints.

Prerequisites

Permission model

Actions and mount points

ActionTable $permissionsRow $permissionsEffect
readYesYesRead all rows of a table / read specified rows
createYes (required to create rows)MeaninglessWho can create rows in the table
update / deleteYesYesModify / delete any rows / specified rows
writeYesYescreate+update+delete (excluding read) shortcut

Decision model (rowSecurity)

OperationrowSecurity: false (default)rowSecurity: true
Create rowMust have table-level createStill must have table-level create
Read / modify / delete rowTable-level permission onlyTable-level or that row's permission (canRead(row) = table.read OR row.read)

Table-level permission is a "grant", not a "restriction": after table-level read(Role.users()) is configured, all session users can read all rows, and row-level $permissions no longer constrains anything. enabled: false disables the whole table for ordinary users, while the API Key can still manage it.

Role constant quick reference

RoleMeaningTypical use
Role.any()Any request (including visitors without a session)Public reads; use cautiously for writes
Role.guests()Visitor without a sessionPre-login exclusive content
Role.users()Any user with a session (including anonymous sessions)Resources available after login
Role.user(userId)Specified userRow owner
Role.team(teamId[, role])Team (member role can be restricted)Team sharing
Role.member(membershipId)Specified membership relationFine-grained team authorization
Role.label(labelId)Users with labelsAdmins / reviewers

Permissions are a union of allows; there are no "explicit deny" rules.

  1. Grant only create when creating the table: createTable({ permissions: [Permission.create(Role.users())], rowSecurity: true, enabled: true }); do not add ordinary users' table-level read/update/delete/write, otherwise row-level isolation is bypassed.

  2. Omit permissions when the client creates rows: the server automatically writes the creator's read/update/delete; business fields such as ownerId can be added, but they are not the permission boundary.

  3. When explicit expression is needed: permissions: [Permission.read(Role.user(自己)), Permission.update(Role.user(自己)), Permission.delete(Role.user(自己))]; do not accept arbitrary ownerId wrapped in Role.user() from page parameters.

  4. Creating rows on behalf of users on the server: API Key requests have no "current end user"; omitting permissions yields empty row permissions—you must first obtain the user ID from a trusted session / JWT, then explicitly grant that user.

  5. Team collaboration: use Role.team(teamId) instead of the uploader's personal update/delete for files / rows, avoiding the 403 where "only the uploader can delete".

Key boundary: Client SDK hasRole constraint

When the Client SDK creates / updates rows, every Role in permissions must pass authorization.hasRole(role):

Therefore the Client SDK cannot grant row-level permissions to others; when needed, go through a Function proxy:

  1. The frontend creates rows containing only itself.

  2. When sharing is needed, call a Function; inside the Function, use the Server SDK to read the row's $permissions, verify the caller is indeed the row owner (x-appwrite-user-id), merge the target user / label permissions, updateRow submit the full set, and leave an audit trail.

  3. Optionally configure an authorization record table (resourceId / granteeId / accessLevel / grantedBy); the frontend directly queries "what am I authorized for", while changes are still done by the Function.

Key boundary: updateRow full replacement

When updateRow is passed with permissions, it is a full replacement, not an incremental append: passing only new permissions loses all original permissions. The correct approach is to first use getRow to read $permissions, add and remove on a copy, then submit the whole set. If permissions is not passed, the original permissions are kept.

Storage permissions (bucket / file)

Errors and boundaries

SDK Category Differences

Example Guide

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Table creation baseline: grant only create (server side)

Under rowSecurity: true anyone can create rows but can only see (or modify, delete) their own rows; do not add ordinary users' table-level read/update/delete/write. No Web tab: creating tables is a server-side action (the Console configures baselines in the UI).

import { Client, TablesDB, Permission, Role } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // Must include /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);
const tablesDB = new TablesDB(client);

await tablesDB.createTable({
    databaseId: 'main',
    tableId: 'private_notes',
    name: 'Private notes',
    permissions: [Permission.create(Role.users())],
    rowSecurity: true,
    enabled: true,
});
// Do not add table-level read/update/delete/write(Role.users()) on top — it would bypass row-level isolation

Client-side row creation: creator exclusive by default

When the Client SDK omits permissions, the server automatically writes the creator's read/update/delete; the Server SDK (API Key) has no "current end user", so it must grant explicitly.

import { ID, Permission, Role } from 'agentbase-node-sdk';

// Omitting permissions in the API Key request yields empty row permissions:
// First obtain the user ID from a trusted session / JWT, then explicitly grant it to that user
const userId = '<从已验证会话 / JWT 取得>';
await tablesDB.createRow({
    databaseId: 'main',
    tableId: 'private_notes',
    rowId: ID.unique(),
    data: { title: 'My note' },
    permissions: [
        Permission.read(Role.user(userId)),
        Permission.update(Role.user(userId)),
        Permission.delete(Role.user(userId)),
    ],
});

Team collaboration sharing and full replacement (updateRow / Role.team)

Passing permissions to updateRow is a full replacement: first use getRow to read $permissions, add and remove on a copy, then submit the whole set; if omitted, the original permissions are kept. The Client SDK cannot grant row-level permissions to others (the hasRole constraint); sharing goes through the Function proxy (see above).

import { Permission, Role } from 'agentbase-node-sdk';

const row = await tablesDB.getRow({ databaseId: 'main', tableId: 'private_notes', rowId: '<rowId>' });
const next = [...row.$permissions, Permission.read(Role.team('dev'))];
await tablesDB.updateRow({
    databaseId: 'main',
    tableId: 'private_notes',
    rowId: '<rowId>',
    permissions: next,          // Passing only new permissions loses all original permissions
});