Notion Users API 与集成身份审计实战:成员/访客/Bot 识别、Email 权限边界、Token 自检与自动化离职巡检工程指南

2026 年 11 月 20 日

一、为什么用 Users API 做成员同步与权限审计经常“找不到 Guest”或邮箱为空? #

在搭建企业级权限巡检、离职账号自动清理或将 Notion 成员目录与飞书/Okta 花名册对账时,工程团队通常首选 Notion Users API(GET /v1/users、GET /v1/users/{user_id}、GET /v1/users/me)。但在实际落地中,最常出现四个让人困惑的数据偏差(账号角色基础请参阅 添加成员到工作区 与 访客权限指南):

  1. 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} 反查。
  2. 所有成员的 person.email 字段全部缺失或返回 undefined:Notion 开发者后台将用户基础资料与邮箱拆分为两级权限。若仅开启了 Read user information without email addresses,接口只会返回 name 与 avatar_url,必须显式勾选 Read user information including email addresses 才会吐出邮箱字段(集成配置参阅 创建 Notion API 集成)。
  3. 把所有返回对象都当成自然人入库,混入了大量 Bot 账号:/v1/users 混合返回 type: "person" 与 type: "bot" 两类对象;其中 bot 节点内嵌 bot.owner(区分个人用户授权或全工作区授权)与 bot.workspace_name,若不做类型过滤就会污染员工通信录。
  4. 多工作区场景下脚本跑错 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 四步工程规范 #

结合 工作区设置和安全 与 企业域名验证及影子工作区收编实战,构建稳定的自动化人员审计管道应遵循以下四步规范:

  1. 按需隔离两类集成的 User Capability 权限:普通内容同步机器人(如文档导出、看板更新)只勾选 Read user information without email addresses 甚至不勾选,遵循最小数据暴露原则;仅安全审计与 HR 离职对账专用的只读集成才开启 Read user information including email addresses。
  2. 所有批处理脚本启动首行执行 /v1/users/me 断言:脚本启动后先获取 bot_id、bot.workspace_name(或 bot.owner),并与环境变量 EXPECTED_WORKSPACE_NAME 比对。若不匹配立即中断退出,从根源阻断测试环境脚本误连生产工作区;同时记录 bot_id 以便在评论或修改日志中过滤机器人自身操作。
  3. 建立“全员列表 + 业务页面 Guest 反查”双通道盘点:先分页遍历 GET /v1/users 拿到全部付费 Member 与工作区内 Bot;再从核心对外交付库或评论接口收集外部 user_id,若不在 Member 集合内则以内存缓存去重后调用 GET /v1/users/{user_id} 补齐 Guest 台账(人员属性写库规范参阅 Person 属性工程实战)。
  4. 与企业 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")
  )
)

五、成员治理高频排错与内部集成自检清单 #

在启用自动巡检或对外同步成员花名册前,请逐项核对以下关键检查点:

  1. 为什么反查某个 Guest UUID 返回 404 object_not_found? 只有当该 Guest 被邀请进入当前集成已连接(Connected)的某个页面时,集成才有权限通过 GET /v1/users/{user_id} 读取该访客信息;若集成未挂载到对应共享页面,接口将按无权限返回 404。
  2. 如何将离职 Member 的私有页面(Private)安全交接? 在 Settings -> People 移除成员会导致其无法访问工作区,因此执行移除前务必先联系管理员或通过企业版内容迁移/接管流程转出其核心页面(参见 权限组设置)。
  3. 多工作区环境如何避免误删? 任何自动移除或告警脚本都必须只做“只读巡检 + 飞书/企微工单推送”,把最终点击 Remove from Team 的操作保留给管理员二次复核,并严格遵守 /v1/users/me 的工作区名称强断言。

若遇到 person.email 始终为空、GET /v1/users 漏掉外协访客或权限报错 403,请对照 Notion 常见报错与故障诊断手册 与 数据库架构设计速查 核验集成能力面板与授权页面范围。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。