Notion Users API 与集成身份审计实战:成员/访客/Bot 识别、Email 权限边界、Token 自检与自动化离职巡检工程指南
一、为什么用 Users API 做成员同步与权限审计经常“找不到 Guest”或邮箱为空? #
在搭建企业级权限巡检、离职账号自动清理或将 Notion 成员目录与飞书/Okta 花名册对账时,工程团队通常首选 Notion Users API(GET /v1/users、GET /v1/users/{user_id}、GET /v1/users/me)。但在实际落地中,最常出现四个让人困惑的数据偏差(账号角色基础请参阅 添加成员到工作区 与 访客权限指南):
GET /v1/users返回结果里根本没有外部访客(Guest):List all users接口仅返回当前工作区内的正式成员(Members/Owner)与已安装机器人(Bots),单页分享邀请进来的Guest不会出现在该列表分页结果中!想要获取 Guest 详情,只能在读取页面的Person属性、created_by、last_edited_by或评论作者拿到user.id后,再单独调用GET /v1/users/{user_id}反查。- 所有成员的
person.email字段全部缺失或返回undefined:Notion 开发者后台将用户基础资料与邮箱拆分为两级权限。若仅开启了Read user information without email addresses,接口只会返回name与avatar_url,必须显式勾选Read user information including email addresses才会吐出邮箱字段(集成配置参阅 创建 Notion API 集成)。 - 把所有返回对象都当成自然人入库,混入了大量 Bot 账号:
/v1/users混合返回type: "person"与type: "bot"两类对象;其中bot节点内嵌bot.owner(区分个人用户授权或全工作区授权)与bot.workspace_name,若不做类型过滤就会污染员工通信录。 - 多工作区场景下脚本跑错 Token 导致越区写入:团队常同时维护测试区与生产区两套
Internal Integration Token或多租户 OAuth Token,执行批量写库前若未先调用GET /v1/users/me校验当前 Bot 所属工作区与授权类型,极易造成跨区错写。
接口端点(Notion-Version: 2025-09-03) | 核心用途 | 可返回对象范围 | 前置权限与核心限制 |
|---|---|---|---|
GET /v1/users/me | Token 自检与工作区身份核验 | 当前调用 Token 对应的 bot 对象及 bot.owner / workspace_name | 无需额外用户读权限即可自检;最适合作为脚本启动前探针 |
GET /v1/users | 分页拉取工作区人员与机器人目录 | 工作区正式 Member / Owner 与 Bot(page_size 最大 100) | 不包含 Guest 访客;返回 email 须开含邮箱读取能力 |
GET /v1/users/{user_id} | 按 UUID 精确反查单个用户资料 | 包括 Member、Bot 以及页面/评论中出现的 Guest | 仅当某 Guest 位于集成可访问的页面中时才可查到其资料 |
页面 Person / 评论 created_by | 间接发现全量外部协作者 UUID | 返回挂在具体条目或讨论中的 User 引用对象(含 Guest) | 配合本地 UUID 缓存去重反查,避免重复触发 3 req/s 限流 |
二、企业身份治理与 Users API 四步工程规范 #
结合 工作区设置和安全 与 企业域名验证及影子工作区收编实战,构建稳定的自动化人员审计管道应遵循以下四步规范:
- 按需隔离两类集成的 User Capability 权限:普通内容同步机器人(如文档导出、看板更新)只勾选
Read user information without email addresses甚至不勾选,遵循最小数据暴露原则;仅安全审计与 HR 离职对账专用的只读集成才开启Read user information including email addresses。 - 所有批处理脚本启动首行执行
/v1/users/me断言:脚本启动后先获取bot_id、bot.workspace_name(或bot.owner),并与环境变量EXPECTED_WORKSPACE_NAME比对。若不匹配立即中断退出,从根源阻断测试环境脚本误连生产工作区;同时记录bot_id以便在评论或修改日志中过滤机器人自身操作。 - 建立“全员列表 + 业务页面 Guest 反查”双通道盘点:先分页遍历
GET /v1/users拿到全部付费 Member 与工作区内 Bot;再从核心对外交付库或评论接口收集外部user_id,若不在 Member 集合内则以内存缓存去重后调用GET /v1/users/{user_id}补齐 Guest 台账(人员属性写库规范参阅 Person 属性工程实战)。 - 与企业 IdP / HR 花名册做邮箱级差集对账:将 Notion 拉取的
person.email(统一转小写)与 HR 在职白名单及企业域名做每日比对,自动标出“已离职未移除账号”、“非企业邮箱占用了付费 Member 席位”以及“长期未清理的未知第三方 OAuth Bot”。
三、Python 实战:Token 工作区自检、全量成员分页与离职异常对账 #
以下脚本完整演示如何在 Notion-Version: 2025-09-03 下,使用 GET /v1/users/me 校验当前 Token 归属工作区,分页拉取全部 person 与 bot,识别缺少 email 权限的场景,并与企业邮箱白名单完成自动化离职/越权对账(含 429 Retry-After 退避):
import os
import time
from typing import Any
import httpx
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
EXPECTED_WORKSPACE = os.environ.get("EXPECTED_WORKSPACE_NAME", "")
HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2025-09-03",
}
def notion_get(client: httpx.Client, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
url = f"https://api.notion.com/v1{path}"
for attempt in range(5):
resp = client.get(url, headers=HEADERS, params=params, timeout=20.0)
if resp.status_code == 429:
time.sleep(float(resp.headers.get("Retry-After", 2 ** attempt)) + 0.25)
continue
resp.raise_for_status()
return resp.json()
raise RuntimeError(f"Users API 请求失败: {path}")
def verify_bot_identity(client: httpx.Client) -> dict[str, Any]:
"""启动探针:校验 Token 所属工作区名称并获取 Bot ID"""
me = notion_get(client, "/users/me")
ws_name = me.get("bot", {}).get("workspace_name", "")
if EXPECTED_WORKSPACE and ws_name != EXPECTED_WORKSPACE:
raise PermissionError(f"工作区校验失败:当前为 '{ws_name}',预期为 '{EXPECTED_WORKSPACE}'")
return {"bot_id": me["id"], "bot_name": me.get("name"), "workspace_name": ws_name}
def audit_workspace_identities(client: httpx.Client, active_hr_emails: set[str]) -> dict[str, list[dict[str, Any]]]:
"""分页遍历工作区全部成员与 Bot,校验邮箱读取权限并输出离职/越权异常清单"""
members, bots, missing_email_users, offboarded_risks = [], [], [], []
cursor: str | None = None
while True:
params: dict[str, Any] = {"page_size": 100}
if cursor:
params["start_cursor"] = cursor
data = notion_get(client, "/users", params=params)
for user in data.get("results", []):
u_type = user.get("type")
if u_type == "bot":
bots.append({
"id": user["id"],
"name": user.get("name"),
"owner_type": user.get("bot", {}).get("owner", {}).get("type"),
})
continue
if u_type == "person":
email = (user.get("person") or {}).get("email", "").strip().lower()
record = {"id": user["id"], "name": user.get("name"), "email": email}
members.append(record)
if not email:
missing_email_users.append(record)
elif email not in active_hr_emails:
offboarded_risks.append(record)
if not data.get("has_more"):
break
cursor = data.get("next_cursor")
time.sleep(0.35)
return {
"members": members,
"bots": bots,
"missing_email_users": missing_email_users,
"offboarded_or_external_members": offboarded_risks,
}
四、Formula 2.0 实战:成员离职滞留与异常 Bot 权限审计门禁 #
将巡检脚本采集的结果写入《工作区身份与席位审计台账》(席位降级省钱策略可参阅 免费版限制与 Guest 协作实战,模型设计参阅 企业级数据库架构设计速查),配置 身份类型(Select:Member/Guest/Bot)、账号邮箱(Email)、HR在职状态(Select:在职/已离职/外部合作)、合作截止日期(Date)与 Bot所有者已报备(Checkbox),并创建如下 身份合规门禁 Formula 2.0 属性(语法参见 Formula 2.0 速查手册):
lets(
identityType, format(prop("身份类型")),
hrStatus, format(prop("HR在职状态")),
email, prop("账号邮箱"),
botApproved, prop("Bot所有者已报备"),
expireDate, prop("合作截止日期"),
isGuestExpired, identityType == "Guest" && !empty(expireDate) && now() > expireDate,
ifs(
identityType == "Bot" && !botApproved,
style("🚨 未报备 Bot:请核查 /users/me 归属与集成权限", "red", "bold", "red_background"),
identityType == "Member" && hrStatus == "已离职",
style("⛔ 高危滞留:已离职员工仍占付费 Member,须立即移除", "red", "bold", "red_background"),
identityType == "Member" && empty(email),
style("⚠️ 邮箱缺失:请为集成补勾 Read email 权限后重跑巡检", "orange", "bold"),
identityType == "Member" && hrStatus == "外部合作",
style("🟠 席位浪费:外协人员不应设为 Member,建议降级为免费 Guest", "orange", "bold", "yellow_background"),
isGuestExpired,
style("🟡 Guest 授权已过期:请从对应页面 Share 中移除", "orange"),
style("🟢 身份与席位状态合规", "green")
)
)
五、成员治理高频排错与内部集成自检清单 #
在启用自动巡检或对外同步成员花名册前,请逐项核对以下关键检查点:
- 为什么反查某个
GuestUUID 返回404 object_not_found? 只有当该 Guest 被邀请进入当前集成已连接(Connected)的某个页面时,集成才有权限通过GET /v1/users/{user_id}读取该访客信息;若集成未挂载到对应共享页面,接口将按无权限返回404。 - 如何将离职 Member 的私有页面(Private)安全交接?
在
Settings -> People移除成员会导致其无法访问工作区,因此执行移除前务必先联系管理员或通过企业版内容迁移/接管流程转出其核心页面(参见 权限组设置)。 - 多工作区环境如何避免误删?
任何自动移除或告警脚本都必须只做“只读巡检 + 飞书/企微工单推送”,把最终点击
Remove from Team的操作保留给管理员二次复核,并严格遵守/v1/users/me的工作区名称强断言。
若遇到
person.email始终为空、GET /v1/users漏掉外协访客或权限报错403,请对照 Notion 常见报错与故障诊断手册 与 数据库架构设计速查 核验集成能力面板与授权页面范围。
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。