AppBase 云控制台
浏览全部文档 · 33/37
已支持已进入 main

Session、JWT、API Key、Scope 与 Permission

权限、安全和项目上下文

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
0363062a1c7ea08741975bb5ba0c3361663c9353

功能简介

AppBase 使用多层授权：Session/JWT 表示用户，API Key 表示服务端应用，Scope 限制接口能力，Organization Role 限制控制面操作，Table/Row/Bucket/File 等 Permission 限制具体资源。任何一层通过都不代表其他层自动通过。

当前支持范围

  • 认证、Scope 与资源权限（SUPPORTED）：用 Session、JWT、API Key、细粒度 Scope、Role 与资源级 Permission 共同保护项目控制面和数据面。

适用场景

  • 为浏览器用户限制可见 Row/File。
  • 为后端服务创建最小 Scope API Key。
  • 把 Organization 管理角色与 Project 数据权限分开。

前置条件

  • 先确定请求属于 Organization 控制面还是 Project 数据面。
  • 列出接口 Action 声明的 AuthType 与 Scope。
  • 为资源设计 read/create/update/delete Permission。

Console 操作路径

Console → Project → Settings → Keys 创建服务端 API Key；Databases/Storage 在资源页面配置 Permission；Organization → Members 管理角色。Secret 只在创建时受控展示和保存。

SDK 示例

SDK · TypeScript
import { Permission, Role } from 'appbase-web-sdk';

const permissions = [
  Permission.read(Role.user('<USER_ID>')),
  Permission.update(Role.user('<USER_ID>')),
  Permission.delete(Role.team('<TEAM_ID>', 'owner'))
];

REST 示例

REST · Bash
curl 'https://<APPBASE_HOST>/v1/tablesdb/<DATABASE_ID>/tables/<TABLE_ID>/rows/<ROW_ID>' \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-JWT: <USER_JWT>'

权限模型

浏览器只使用 Session/JWT；API Key 仅用于受信服务端并最小化 Scope；Organization 控制面需要 Console Session/Admin/JWT。不可见资源可与不存在资源等价，防止枚举。

常见错误

现象处理建议
401缺少允许的身份；先建立 Session/JWT 或在服务端设置 Key。
403身份有效但 Role、Scope 或 Permission 不足。
404资源不存在或不可见；不要提示“它其实存在”。
Key 泄漏立即撤销并轮换，排查日志、错误响应和客户端包。

当前限制

  • Project ID 不是 Secret，但它不能替代任何授权。
  • Owner/Admin 角色不应被复制为终端用户数据 Permission。
  • 不能通过关闭所有 Authorization、扩大读取权限或放宽 Membership 解决业务错误。

Appwrite 兼容说明

Session、JWT、API Key、Role 与 Permission 的核心概念保持兼容；Organization Role 是 AppBase 控制面增强。

AppBase 增强说明

AppBase 把 Organization、Project 与 AI 服务统一放进明确的认证、Scope 和资源权限边界。

发布状态和验证 Commit

origin/main 已核验。验证 Commit：0363062a1c7ea08741975bb5ba0c3361663c9353。

权威来源文件列表

  • backend-candidate:app/controllers/api/projects.php
  • backend-candidate:src/Appwrite/Platform/Modules/*/Http/
  • backend-candidate:tests/e2e/Services/Databases/DatabasesBase.php
  • backend-candidate:tests/e2e/Services/Storage/StorageCustomClientTest.php

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/advanced/security。上游页面不是 AppBase 实现证据。

继续阅读