受控身份目录

业务 App 使用受控身份目录同步或按需查询当前组织内可用的员工与外部账号。该接口只提供身份和组织上下文，不提供业务角色、权限或业务数据范围。

前置条件

1. Auth 管理员已经为业务 App 创建 Service Account。
2. Service Account 绑定目标 App 和目标组织。
3. Service Token 包含 auth.directory.read scope。
4. 目标组织已开通该 App。

Service Token 只能放在业务 App 服务端 Secret 管理中，不得发送给浏览器或写入仓库。

API

GET /v1/directory/users?organizationId={organizationId}&appKey={appKey}&limit=50
Authorization: Bearer iwa_...

可选参数：

• query：按姓名或邮箱模糊搜索，最长 120 个字符。
• cursor：上一页返回的 nextCursor。
• limit：1 至 100，默认 50。

响应只包含：

• 稳定的 IWish Auth User ID。
• 邮箱、显示名称和头像。
• email 或 feishu 身份来源。
• 账号状态。
• 飞书员工的在职状态、职位和部门名称。

不返回手机号、飞书原始凭据、OAuth Token、客户项目数据、平台角色或业务权限。

TypeScript

import { createIWishAuthClient } from "@iwish/auth-sdk";

const auth = createIWishAuthClient({
  apiUrl: process.env.IWISH_AUTH_API_URL!,
  token: process.env.IWISH_AUTH_SERVICE_TOKEN!
});

const page = await auth.listIdentityDirectory({
  organizationId: process.env.IWISH_AUTH_ORGANIZATION_ID!,
  appKey: "crm",
  limit: 50
});

Python

from iwish_auth import IWishAuthClient

async with IWishAuthClient(
    api_url=AUTH_API_URL,
    token=AUTH_SERVICE_TOKEN,
) as auth:
    page = await auth.list_identity_directory(
        organization_id=AUTH_ORGANIZATION_ID,
        app_key="crm",
        limit=50,
    )

拒绝规则

• 401 invalid_service_token：Token 无效、撤销或过期。
• 403 insufficient_service_scope：缺少 auth.directory.read。
• 403 service_scope_mismatch：Token 与目标组织或 App 不匹配。
• 组织、App、成员、账号或飞书员工状态不可用时，该身份不会进入可用目录。

业务 App 必须用 user.id 建立本地成员外键，并继续在本地管理角色、权限和数据范围。