{ "openapi": "3.1.0", "info": { "title": "IWish Auth API", "version": "1.0.0-rc.1", "description": "IWish Auth 统一身份、飞书组织、客户项目上下文与跨 App SSO API。业务 App 的成员、角色、权限和数据授权由业务 App 自己管理。" }, "servers": [ { "url": "https://auth-api-staging.iwishapp.cn", "description": "IWish Auth dev/staging API" } ], "paths": { "/health": { "get": { "summary": "Worker 存活检查", "description": "不访问外部依赖，仅证明当前 Worker 可执行。", "responses": { "200": { "description": "Worker 存活", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "service", "environment", "release" ], "properties": { "ok": { "const": true }, "service": { "const": "iwish-auth-api" }, "environment": { "type": "string", "enum": [ "dev", "staging", "prod" ] }, "release": { "type": "string" } } } } } } } } }, "/v1/me": { "get": { "summary": "Get current user context", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current user, organizations, and enabled apps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUserContext" } } } }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Supabase user is not mapped to an active IWish Auth user" } } } }, "/v1/sso/authorize": { "post": { "summary": "Create a one-time SSO authorization code", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Exact allowlisted callback URL with a 60-second authorization code" }, "400": { "description": "Invalid request, callback, or client" }, "401": { "description": "Missing or invalid Portal session" }, "403": { "description": "Organization or App access denied" } } } }, "/v1/sso/token": { "post": { "summary": "Exchange an authorization code for an opaque App session", "responses": { "200": { "description": "App session token and app-scoped user context" }, "400": { "description": "Invalid, expired, replayed, or PKCE-mismatched grant" }, "401": { "description": "Invalid confidential client credentials" } }, "description": "业务 App 服务端使用 client secret、PKCE verifier 和一次性 code 换取不透明 App Session；不返回 Auth 业务权限。" } }, "/v1/sso/session": { "get": { "summary": "解析当前 App Session 0.3", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "App Session 0.3 application_owned 上下文", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppSessionContext" } } } }, "401": { "description": "Session is missing, invalid, expired, or revoked" }, "403": { "description": "Client, user, organization, or App access is no longer active" } }, "description": "仅返回身份、员工、部门、客户项目上下文、组织和 App 元数据；不返回业务角色或业务权限。" } }, "/v1/sso/logout": { "post": { "summary": "Revoke the current App session", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Session revocation result" } } } }, "/v1/sso/logout-all": { "post": { "summary": "Revoke all active App sessions for the current Portal user", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Number of revoked sessions" } } } }, "/v1/admin/apps/{appId}/sso-clients": { "get": { "summary": "List SSO clients and exact callbacks for an App", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OAuth Client 列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "clients" ], "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/SsoClientSummary" } } } } } } } }, "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "adminOrganizationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "post": { "summary": "Create a confidential SSO client", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "OAuth Client 与仅展示一次的明文 Secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "client", "clientSecret" ], "properties": { "client": { "$ref": "#/components/schemas/SsoClientSummary" }, "clientSecret": { "type": "string", "readOnly": true, "description": "仅在创建或轮换响应中展示一次的明文 Secret" } } } } } } }, "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "name", "environment", "redirectUris" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "environment": { "type": "string", "enum": [ "dev", "staging", "prod" ] }, "sessionTtlSeconds": { "type": "integer", "minimum": 900, "maximum": 86400, "default": 28800 }, "redirectUris": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri", "maxLength": 2048 } } } } } } } } }, "/v1/admin/sso-clients/{clientId}/rotate-secret": { "post": { "summary": "Rotate an SSO client secret and revoke its App sessions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OAuth Client 与仅展示一次的明文 Secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "client", "clientSecret" ], "properties": { "client": { "$ref": "#/components/schemas/SsoClientSummary" }, "clientSecret": { "type": "string", "readOnly": true, "description": "仅在创建或轮换响应中展示一次的明文 Secret" } } } } } } }, "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } } } }, "/v1/admin/sso-clients/{clientId}/redirect-uris": { "post": { "summary": "Add an exact callback URL", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Updated client configuration" } }, "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "redirectUri" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "redirectUri": { "type": "string", "format": "uri", "maxLength": 2048 } } } } } } }, "delete": { "summary": "Delete an exact callback URL while retaining at least one", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Updated client configuration" } }, "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "redirectUri" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "redirectUri": { "type": "string", "format": "uri", "maxLength": 2048 } } } } } } } }, "/v1/admin/users": { "post": { "summary": "Create a user with an initial password", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created user and organization membership" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.users.create permission" } } }, "get": { "summary": "List admin users", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Admin user list" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } } } }, "/v1/admin/invitations": { "post": { "summary": "Invite a user by email", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Invited user and organization membership" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.users.invite permission" } } }, "get": { "summary": "查询外部账号邀请", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] } } ], "responses": { "200": { "description": "邀请列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "invitations" ], "properties": { "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationSummary" } } } } } } }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.invitations.manage" } } } }, "/v1/admin/organizations": { "post": { "summary": "Create an organization", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created organization" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organizations.create permission" } } }, "get": { "summary": "List organizations", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Organization list" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } } } }, "/v1/admin/organizations/{organizationId}/apps": { "post": { "summary": "Enable an app for an organization", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Enabled organization app" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.apps.enable permission" } } } }, "/v1/admin/users/{userId}/disable": { "patch": { "summary": "Disable a user", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Disabled user" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.users.disable permission" } } } }, "/v1/admin/users/{userId}/restore": { "patch": { "summary": "Restore a user", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId" ], "properties": { "organizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Restored user" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.users.restore permission" }, "502": { "description": "Repository operation failed" } } } }, "/v1/apps/{appKey}/manifest": { "get": { "summary": "Get latest app manifest", "parameters": [ { "name": "appKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "dev", "staging", "prod" ] } } ], "responses": { "200": { "description": "Latest manifest" }, "400": { "description": "Invalid environment" }, "502": { "description": "Repository operation failed" } } }, "post": { "summary": "Manifest write moved to Admin API", "deprecated": true, "parameters": [ { "name": "appKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "410": { "description": "Manifest write must use /v1/admin/apps/{appKey}/manifest/sync" } } } }, "/v1/admin/users/{userId}": { "get": { "summary": "Get admin user detail", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Admin user detail" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } }, "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/admin/organizations/{organizationId}": { "get": { "summary": "Get organization detail", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Organization detail" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "patch": { "summary": "Update organization", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "name", "type" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "internal", "client" ] } } } } } }, "responses": { "200": { "description": "Organization lifecycle operation completed" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organizations.update permission" } } } }, "/v1/admin/apps": { "get": { "summary": "List apps", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "App list" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } } } }, "/v1/admin/apps/{appId}": { "get": { "summary": "Get app detail", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "App detail" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } }, "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/admin/roles": { "get": { "summary": "查询 Auth 平台内部角色", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Role list" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } }, "description": "仅返回 appKey=auth 的平台管理角色，不承载业务 App 角色。" } }, "/v1/admin/permissions": { "get": { "summary": "查询 Auth 平台内部权限", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Permission list" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } }, "description": "仅返回 appKey=auth 的平台管理权限，不承载业务 App 权限节点。" } }, "/v1/admin/audit-logs": { "get": { "summary": "List audit logs", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Audit log list" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } } } }, "/v1/admin/organizations/{organizationId}/apps/{appId}/disable": { "patch": { "summary": "Disable an app for an organization", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Disabled organization app" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have required admin permission" } }, "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/admin/organizations/{organizationId}/disable": { "patch": { "summary": "Disable organization", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Organization lifecycle operation completed" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organizations.disable permission" } } } }, "/v1/admin/organizations/{organizationId}/restore": { "patch": { "summary": "Restore organization", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Organization lifecycle operation completed" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organizations.restore permission" } } } }, "/v1/admin/organizations/{organizationId}/members": { "post": { "summary": "Add a member to an organization", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "userId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "invited", "disabled" ] } } } } } }, "responses": { "201": { "description": "Added organization member" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organization_members.manage permission" }, "502": { "description": "Repository operation failed" } } } }, "/v1/admin/organizations/{organizationId}/members/{userId}/disable": { "patch": { "summary": "Disable an organization member", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Disabled organization member" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organization_members.manage permission" }, "502": { "description": "Repository operation failed" } } } }, "/v1/admin/organizations/{organizationId}/members/{userId}/restore": { "patch": { "summary": "Restore an organization member", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Restored organization member" }, "400": { "description": "Invalid request or path parameter" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.organization_members.manage permission" }, "502": { "description": "Repository operation failed" } } } }, "/v1/admin/apps/{appKey}/manifest/validate": { "post": { "summary": "Validate app manifest and preview governance diff", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "appKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "manifest" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "manifest": { "$ref": "#/components/schemas/AuthManifest" } } } } } }, "responses": { "200": { "description": "Manifest validation preview" }, "400": { "description": "Invalid request, invalid manifest, or app key mismatch" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.manifest.write permission" }, "502": { "description": "Repository operation failed" } } } }, "/v1/admin/apps/{appKey}/manifest/sync": { "post": { "summary": "Sync app manifest after governance confirmation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "appKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "confirmed", "manifest" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "manifest": { "$ref": "#/components/schemas/AuthManifest" }, "confirmed": { "type": "boolean", "const": true } } } } } }, "responses": { "200": { "description": "Manifest sync result" }, "400": { "description": "Invalid request, invalid manifest, or app key mismatch" }, "401": { "description": "Missing or invalid Bearer token" }, "403": { "description": "Actor does not have auth.manifest.write permission" }, "502": { "description": "Repository operation failed" } } } }, "/v1/integrations/feishu/oauth/token": { "post": { "summary": "Adapt OAuth token exchange from Supabase Auth to Feishu", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "format": "password" }, "code": { "type": "string" }, "refresh_token": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string" } } } } } }, "responses": { "200": { "description": "OAuth token response" }, "400": { "description": "Invalid or unsupported grant" }, "401": { "description": "Invalid adapter client credentials" }, "502": { "description": "Feishu token exchange failed" } } } }, "/v1/integrations/feishu/oauth/userinfo": { "get": { "summary": "Adapt Feishu UserInfo for Supabase Auth", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Normalized OAuth UserInfo" }, "401": { "description": "Missing user access token" }, "403": { "description": "Tenant mismatch or inactive employee" }, "502": { "description": "Feishu UserInfo failed" } } } }, "/v1/admin/feishu/status": { "get": { "summary": "Get masked Feishu configuration and last sync status", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feishu status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeishuStatus" } } } }, "400": { "description": "Invalid organization ID" }, "401": { "description": "Invalid token" }, "403": { "description": "Missing auth.feishu.read" } } } }, "/v1/admin/feishu/sync": { "post": { "summary": "Run a full Feishu directory synchronization", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Synchronization completed" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid token" }, "403": { "description": "Missing auth.feishu.sync" }, "409": { "description": "Synchronization already running" }, "502": { "description": "Feishu synchronization failed" }, "503": { "description": "Feishu is not configured" } } } }, "/v1/admin/feishu/sync-runs": { "get": { "summary": "List Feishu synchronization history", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Synchronization history", "content": { "application/json": { "schema": { "type": "object", "required": [ "syncRuns" ], "properties": { "syncRuns": { "type": "array", "items": { "$ref": "#/components/schemas/FeishuSyncRun" } } } } } } }, "400": { "description": "Invalid query" }, "401": { "description": "Invalid token" }, "403": { "description": "Missing auth.feishu.read" }, "503": { "description": "Feishu is not configured" } } } }, "/v1/admin/client-projects": { "get": { "summary": "查询客户项目", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "客户项目列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/AdminClientSummary" } } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } }, "post": { "summary": "创建独立客户项目", "description": "无需外部客户账号或客户组织即可创建", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "clientCode", "name" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "clientCode": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "shortName": { "type": [ "string", "null" ] }, "serviceStartDate": { "type": [ "string", "null" ], "format": "date" }, "serviceEndDate": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "201": { "description": "客户项目已创建", "content": { "application/json": { "schema": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/AdminClientSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-projects/{projectId}": { "get": { "summary": "查询客户项目详情", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "客户项目和项目团队", "content": { "application/json": { "schema": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/AdminClientDetail" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } }, "patch": { "summary": "更新客户项目", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "name" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "shortName": { "type": [ "string", "null" ] }, "serviceStartDate": { "type": [ "string", "null" ], "format": "date" }, "serviceEndDate": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "客户项目已更新", "content": { "application/json": { "schema": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/AdminClientSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-projects/{projectId}/disable": { "patch": { "summary": "停用客户项目", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "客户项目已停用", "content": { "application/json": { "schema": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/AdminClientSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-projects/{projectId}/restore": { "patch": { "summary": "恢复客户项目", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "客户项目已恢复", "content": { "application/json": { "schema": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/AdminClientSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-team-roles": { "get": { "summary": "查询项目职责目录", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "项目职责列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/ClientTeamRoleSummary" } } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-team-assignments": { "get": { "summary": "查询项目团队分工", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "可选的内部管理授权域 ID；写请求必须在请求体中提供" }, { "name": "userId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "roleId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled" ] } } ], "responses": { "200": { "description": "项目团队分工列表", "content": { "application/json": { "schema": { "type": "object", "required": [ "assignments" ], "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/ClientTeamAssignmentSummary" } } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } }, "post": { "summary": "新增项目团队分工", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "roleId", "isPrimary", "platformScopes", "source", "validFrom", "userId", "clientId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "roleId": { "type": "string", "format": "uuid" }, "isPrimary": { "type": "boolean" }, "platformScopes": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "import", "api" ] }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "userId": { "type": "string", "format": "uuid" }, "clientId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "项目团队分工已创建", "content": { "application/json": { "schema": { "type": "object", "required": [ "assignment" ], "properties": { "assignment": { "$ref": "#/components/schemas/ClientTeamAssignmentSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-team-assignments/{assignmentId}": { "patch": { "summary": "更新项目团队分工", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId", "roleId", "isPrimary", "platformScopes", "source", "validFrom" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" }, "roleId": { "type": "string", "format": "uuid" }, "isPrimary": { "type": "boolean" }, "platformScopes": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "import", "api" ] }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "项目团队分工已更新", "content": { "application/json": { "schema": { "type": "object", "required": [ "assignment" ], "properties": { "assignment": { "$ref": "#/components/schemas/ClientTeamAssignmentSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-team-assignments/{assignmentId}/disable": { "patch": { "summary": "停用项目团队分工", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "项目团队分工已停用", "content": { "application/json": { "schema": { "type": "object", "required": [ "assignment" ], "properties": { "assignment": { "$ref": "#/components/schemas/ClientTeamAssignmentSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/client-team-assignments/{assignmentId}/restore": { "patch": { "summary": "恢复项目团队分工", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "assignmentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "项目团队分工已恢复", "content": { "application/json": { "schema": { "type": "object", "required": [ "assignment" ], "properties": { "assignment": { "$ref": "#/components/schemas/ClientTeamAssignmentSummary" } } } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/feishu/directory": { "get": { "summary": "查询飞书公司组织目录", "description": "返回同步后的飞书部门树和员工目录；飞书员工即内部统一身份", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "可选的内部管理授权域 ID；写请求必须在请求体中提供" } ], "responses": { "200": { "description": "飞书部门和员工目录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeishuDirectory" } } } }, "400": { "description": "请求参数不符合契约" }, "401": { "description": "Bearer token 缺失或无效" }, "403": { "description": "调用者不在内部管理授权域或缺少对应权限" }, "404": { "description": "客户项目、职责或项目分工不存在" }, "409": { "description": "状态、唯一性、员工有效性或生效期冲突" } } } }, "/v1/admin/service-accounts": { "get": { "summary": "查询服务账号与令牌元数据", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.service_accounts.read" }, "429": { "description": "请求频率超限" } } }, "post": { "summary": "创建服务账号", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.service_accounts.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/service-accounts/{id}/disable": { "post": { "summary": "停用服务账号", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.service_accounts.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/service-accounts/{id}/restore": { "post": { "summary": "恢复服务账号", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.service_accounts.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/service-accounts/{id}/tokens": { "post": { "summary": "签发服务令牌", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.service_accounts.manage" }, "429": { "description": "请求频率超限" } }, "description": "plaintextToken 仅在本次响应中出现，响应禁止缓存；数据库只保存 HMAC-SHA256 hash。" } }, "/v1/admin/service-tokens/{id}/revoke": { "post": { "summary": "吊销服务令牌", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.service_accounts.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/webhook-endpoints": { "get": { "summary": "查询 Webhook endpoint", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.read" }, "429": { "description": "请求频率超限" } } }, "post": { "summary": "创建 Webhook endpoint", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.manage" }, "429": { "description": "请求频率超限" } }, "description": "signingSecret 仅在本次响应中出现。生产环境 URL 必须为公网 HTTPS。" } }, "/v1/admin/webhook-endpoints/{id}": { "patch": { "summary": "更新 Webhook endpoint", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/webhook-endpoints/{id}/disable": { "post": { "summary": "停用 Webhook endpoint", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/webhook-endpoints/{id}/restore": { "post": { "summary": "恢复 Webhook endpoint", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/webhook-endpoints/{id}/rotate-secret": { "post": { "summary": "轮换 Webhook 签名密钥", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.manage" }, "429": { "description": "请求频率超限" } }, "description": "新 signingSecret 仅显示一次；旧版本立即失效。" } }, "/v1/admin/webhook-deliveries": { "get": { "summary": "查询 Webhook 投递、失败与死信", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.read" }, "429": { "description": "请求频率超限" } } } }, "/v1/admin/webhook-deliveries/{id}/retry": { "post": { "summary": "人工重试 Webhook 投递", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "adminOrganizationId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.webhooks.manage" }, "429": { "description": "请求频率超限" } } } }, "/v1/directory/users": { "get": { "summary": "查询当前业务 App 可见的最小身份目录", "description": "仅接受具备 auth.directory.read scope 且绑定到目标组织和 App 的 Service Token。", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "appKey", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "受控身份目录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityDirectoryPage" } } } }, "401": { "description": "Service Token 缺失或无效" }, "403": { "description": "缺少 scope，或 Token 与组织/App 不匹配" } } } }, "/v1/me/password-changed": { "post": { "summary": "确认当前外部账号已完成密码更新", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "账号状态已更新" }, "401": { "description": "登录令牌无效" }, "403": { "description": "飞书员工不允许使用密码入口" } } } }, "/v1/admin/invitations/{invitationId}/revoke": { "patch": { "summary": "撤销外部账号邀请", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.invitations.manage" } } } }, "/v1/admin/invitations/{invitationId}/resend": { "post": { "summary": "重新发送外部账号邀请", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "adminOrganizationId": { "type": "string", "format": "uuid" }, "expiresInHours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 72 } } } } } }, "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.invitations.manage" } } } }, "/v1/admin/users/{userId}/password-reset": { "post": { "summary": "向外部账号发送密码重置邮件", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "organizationId" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "成功" }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.users.password_reset" } } } }, "/v1/admin/sso-clients/{clientId}/disable": { "patch": { "summary": "停用 OAuth Client 并立即撤销授权码和 App Session", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "更新后的 OAuth Client", "content": { "application/json": { "schema": { "type": "object", "required": [ "client" ], "properties": { "client": { "$ref": "#/components/schemas/SsoClientSummary" } } } } } }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.apps.enable" } } } }, "/v1/admin/sso-clients/{clientId}/restore": { "patch": { "summary": "恢复 OAuth Client", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "adminOrganizationId" ], "properties": { "adminOrganizationId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "更新后的 OAuth Client", "content": { "application/json": { "schema": { "type": "object", "required": [ "client" ], "properties": { "client": { "$ref": "#/components/schemas/SsoClientSummary" } } } } } }, "401": { "description": "登录令牌无效" }, "403": { "description": "缺少 auth.apps.enable" } } } }, "/ready": { "get": { "summary": "API 依赖就绪检查", "description": "服务端最小化检查 Supabase；不返回连接串、错误详情或任何 Secret。", "responses": { "200": { "description": "API 与 Supabase 均可用", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "service", "status", "environment", "release" ], "properties": { "ok": { "const": true }, "service": { "const": "iwish-auth-api" }, "status": { "const": "ready" }, "environment": { "type": "string", "enum": [ "dev", "staging", "prod" ] }, "release": { "type": "string" } } } } } }, "503": { "description": "依赖不可用或服务端配置不完整" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "CurrentEmployeeContext": { "type": "object", "required": [ "feishuUserId", "openId", "unionId", "employeeNo", "workEmail", "jobTitle", "managerUserId", "departmentIds", "departmentNames", "employmentStatus", "lastSyncedAt" ], "properties": { "feishuUserId": { "type": "string" }, "openId": { "type": "string" }, "unionId": { "type": [ "string", "null" ] }, "employeeNo": { "type": [ "string", "null" ] }, "workEmail": { "type": [ "string", "null" ], "format": "email" }, "jobTitle": { "type": [ "string", "null" ] }, "managerUserId": { "type": [ "string", "null" ], "format": "uuid" }, "departmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "departmentNames": { "type": "array", "items": { "type": "string" } }, "employmentStatus": { "type": "string", "enum": [ "active", "inactive", "frozen", "resigned", "not_joined", "not_found" ] }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "CurrentUserContext": { "type": "object", "required": [ "user", "employee", "clientAssignments", "organizations", "apps", "recentApps" ], "properties": { "user": { "type": "object", "required": [ "id", "supabaseUserId", "email", "displayName", "avatarUrl", "status", "identitySource" ], "properties": { "id": { "type": "string", "format": "uuid" }, "supabaseUserId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "displayName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": "string", "enum": [ "active", "invited", "disabled", "pending_password_reset" ] }, "identitySource": { "type": "string", "enum": [ "email", "feishu" ] } } }, "employee": { "oneOf": [ { "$ref": "#/components/schemas/CurrentEmployeeContext" }, { "type": "null" } ] }, "organizations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "apps": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "clientAssignments": { "type": "array", "description": "当前飞书员工有效的客户项目职责，不等同于业务数据最终授权", "items": { "$ref": "#/components/schemas/CurrentClientAssignment" } }, "recentApps": { "type": "array", "items": { "$ref": "#/components/schemas/PortalRecentApp" } } } }, "FeishuSyncRun": { "type": "object", "required": [ "id", "triggerType", "status", "departmentCount", "employeeCount", "disabledEmployeeCount", "errorCode", "errorMessage", "feishuLogId", "startedAt", "finishedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "triggerType": { "type": "string", "enum": [ "manual", "scheduled" ] }, "status": { "type": "string", "enum": [ "running", "succeeded", "partial", "failed" ] }, "departmentCount": { "type": "integer", "minimum": 0 }, "employeeCount": { "type": "integer", "minimum": 0 }, "disabledEmployeeCount": { "type": "integer", "minimum": 0 }, "errorCode": { "type": [ "string", "null" ] }, "errorMessage": { "type": [ "string", "null" ] }, "feishuLogId": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FeishuStatus": { "type": "object", "required": [ "configured", "tenantKeyMasked", "schedule", "lastSuccessfulSyncAt", "lastRun" ], "properties": { "configured": { "type": "boolean" }, "tenantKeyMasked": { "type": [ "string", "null" ] }, "schedule": { "type": "string", "example": "*/15 * * * *" }, "lastSuccessfulSyncAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRun": { "oneOf": [ { "$ref": "#/components/schemas/FeishuSyncRun" }, { "type": "null" } ] } } }, "AdminClientSummary": { "type": "object", "required": [ "id", "clientCode", "name", "shortName", "status", "serviceStartDate", "serviceEndDate", "notes", "activeAssignmentCount", "totalAssignmentCount", "createdBy", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "clientCode": { "type": "string" }, "name": { "type": "string" }, "shortName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "serviceStartDate": { "type": [ "string", "null" ], "format": "date" }, "serviceEndDate": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "activeAssignmentCount": { "type": "integer", "minimum": 0 }, "totalAssignmentCount": { "type": "integer", "minimum": 0 }, "createdBy": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CurrentClientAssignmentRole": { "type": "object", "required": [ "assignmentId", "code", "name", "category", "isPrimary", "platformScopes", "validFrom", "validUntil" ], "properties": { "assignmentId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "project", "sales", "technology", "operations", "advertising", "service", "other" ] }, "isPrimary": { "type": "boolean" }, "platformScopes": { "type": "array", "items": { "type": "string" } }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": [ "string", "null" ], "format": "date" } } }, "CurrentClientAssignment": { "type": "object", "required": [ "clientId", "clientCode", "clientName", "shortName", "roles" ], "properties": { "clientId": { "type": "string", "format": "uuid" }, "clientCode": { "type": "string" }, "clientName": { "type": "string" }, "shortName": { "type": [ "string", "null" ] }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/CurrentClientAssignmentRole" } } } }, "ClientTeamRoleSummary": { "type": "object", "required": [ "id", "code", "name", "category", "description", "status", "sortOrder" ], "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "project", "sales", "technology", "operations", "advertising", "service", "other" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "sortOrder": { "type": "integer" } } }, "ClientTeamAssignmentSummary": { "type": "object", "required": [ "id", "userId", "userEmail", "userDisplayName", "userAvatarUrl", "clientId", "clientCode", "clientName", "roleId", "roleCode", "roleName", "roleCategory", "isPrimary", "platformScopes", "status", "source", "validFrom", "validUntil", "notes", "createdBy", "disabledBy", "disabledAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "userEmail": { "type": "string", "format": "email" }, "userDisplayName": { "type": [ "string", "null" ] }, "userAvatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "clientId": { "type": "string", "format": "uuid" }, "clientCode": { "type": "string" }, "clientName": { "type": "string" }, "roleId": { "type": "string", "format": "uuid" }, "roleCode": { "type": "string" }, "roleName": { "type": "string" }, "roleCategory": { "type": "string", "enum": [ "project", "sales", "technology", "operations", "advertising", "service", "other" ] }, "isPrimary": { "type": "boolean" }, "platformScopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "source": { "type": "string", "enum": [ "manual", "import", "api" ] }, "validFrom": { "type": "string", "format": "date" }, "validUntil": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "createdBy": { "type": [ "string", "null" ], "format": "uuid" }, "disabledBy": { "type": [ "string", "null" ], "format": "uuid" }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "AdminClientDetail": { "allOf": [ { "$ref": "#/components/schemas/AdminClientSummary" }, { "type": "object", "required": [ "assignments" ], "properties": { "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/ClientTeamAssignmentSummary" } } } } ] }, "FeishuDirectoryDepartment": { "type": "object", "required": [ "id", "openDepartmentId", "parentOpenDepartmentId", "name", "leaderUserId", "sortOrder", "status", "memberCount", "lastSyncedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "openDepartmentId": { "type": "string" }, "parentOpenDepartmentId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "leaderUserId": { "type": [ "string", "null" ] }, "sortOrder": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "active", "deleted" ] }, "memberCount": { "type": "integer", "minimum": 0 }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FeishuDirectoryEmployee": { "type": "object", "required": [ "userId", "feishuUserId", "displayName", "avatarUrl", "workEmail", "employeeNo", "jobTitle", "managerUserId", "managerName", "departmentIds", "departmentNames", "primaryDepartmentId", "employmentStatus", "lastSyncedAt" ], "properties": { "userId": { "type": "string", "format": "uuid" }, "feishuUserId": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "workEmail": { "type": [ "string", "null" ], "format": "email" }, "employeeNo": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "managerUserId": { "type": [ "string", "null" ] }, "managerName": { "type": [ "string", "null" ] }, "departmentIds": { "type": "array", "items": { "type": "string" } }, "departmentNames": { "type": "array", "items": { "type": "string" } }, "primaryDepartmentId": { "type": [ "string", "null" ] }, "employmentStatus": { "type": "string", "enum": [ "active", "inactive", "frozen", "resigned", "not_joined", "not_found" ] }, "lastSyncedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "FeishuDirectory": { "type": "object", "required": [ "departments", "employees" ], "properties": { "departments": { "type": "array", "items": { "$ref": "#/components/schemas/FeishuDirectoryDepartment" } }, "employees": { "type": "array", "items": { "$ref": "#/components/schemas/FeishuDirectoryEmployee" } } } }, "WebhookEnvelope": { "type": "object", "required": [ "id", "type", "version", "occurredAt", "actor", "subject", "cacheInvalidation", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "examples": [ "client_team.changed" ] }, "version": { "type": "string", "const": "1.0" }, "occurredAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": [ "string", "null" ], "format": "uuid" }, "appKey": { "type": [ "string", "null" ] }, "actor": { "type": "object", "properties": { "userId": { "type": [ "string", "null" ], "format": "uuid" } } }, "subject": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": [ "string", "null" ] } } }, "cacheInvalidation": { "type": "object", "required": [ "userIds", "organizationIds", "appKeys", "clientProjectIds" ], "properties": { "userIds": { "type": "array", "items": { "type": "string" } }, "organizationIds": { "type": "array", "items": { "type": "string" } }, "appKeys": { "type": "array", "items": { "type": "string" } }, "clientProjectIds": { "type": "array", "items": { "type": "string" } } } }, "data": { "type": "object", "additionalProperties": true } } }, "AuthManifest": { "$id": "https://auth-docs-staging.iwishapp.cn/auth-manifest.schema.json", "title": "IWish Auth Business App Manifest", "description": "Business App registration and required Auth context contract. Business roles and permissions remain application-owned.", "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "manifestVersion", "environment", "appKey", "name", "appUrl", "authorizationMode", "requiredContext" ], "properties": { "$schema": { "type": "string", "format": "uri" }, "schemaVersion": { "const": "2.0" }, "manifestVersion": { "type": "string", "minLength": 1 }, "environment": { "enum": [ "dev", "staging", "prod" ] }, "appKey": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "appUrl": { "type": "string", "format": "uri", "pattern": "^https://" }, "authorizationMode": { "const": "application_owned" }, "requiredContext": { "type": "array", "uniqueItems": true, "items": { "enum": [ "identity", "employee", "departments", "clientAssignments" ] } } } }, "AppSessionContext": { "type": "object", "additionalProperties": false, "required": [ "sessionVersion", "authorizationDomain", "session", "user", "employee", "clientAssignments", "organization", "app" ], "properties": { "sessionVersion": { "type": "string", "const": "0.3" }, "authorizationDomain": { "type": "string", "const": "application" }, "session": { "type": "object", "additionalProperties": false, "required": [ "id", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "user": { "$ref": "#/components/schemas/CurrentUserContext/properties/user" }, "employee": { "oneOf": [ { "$ref": "#/components/schemas/CurrentEmployeeContext" }, { "type": "null" } ] }, "clientAssignments": { "type": "array", "description": "客户项目与服务职责上下文，不是业务授权凭证。", "items": { "$ref": "#/components/schemas/CurrentClientAssignment" } }, "organization": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "type", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "internal", "client" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } }, "app": { "type": "object", "additionalProperties": false, "required": [ "appKey", "name", "status", "appUrl", "authorizationMode" ], "properties": { "appKey": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled", "beta", "internal_only" ] }, "appUrl": { "type": [ "string", "null" ], "format": "uri" }, "authorizationMode": { "type": "string", "const": "application_owned" } } } } }, "PortalRecentApp": { "type": "object", "additionalProperties": false, "required": [ "organizationId", "appKey", "name", "appUrl", "lastOpenedAt", "openCount" ], "properties": { "organizationId": { "type": "string", "format": "uuid" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "appUrl": { "type": [ "string", "null" ], "format": "uri" }, "lastOpenedAt": { "type": "string", "format": "date-time" }, "openCount": { "type": "integer", "minimum": 1 } } }, "DirectoryUser": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "displayName", "avatarUrl", "identitySource", "status", "employee" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "displayName": { "type": [ "string", "null" ] }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri" }, "identitySource": { "type": "string", "enum": [ "email", "feishu" ] }, "status": { "type": "string", "enum": [ "active", "invited", "disabled", "pending_password_reset" ] }, "employee": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "employmentStatus", "jobTitle", "departmentNames" ], "properties": { "employmentStatus": { "type": "string", "enum": [ "active", "inactive", "frozen", "resigned", "not_joined", "not_found" ] }, "jobTitle": { "type": [ "string", "null" ] }, "departmentNames": { "type": "array", "items": { "type": "string" } } } }, { "type": "null" } ] } } }, "IdentityDirectoryPage": { "type": "object", "additionalProperties": false, "required": [ "users", "nextCursor" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryUser" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "InvitationSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "organizationId", "userId", "status", "redirectTo", "expiresAt", "resendCount", "lastSentAt", "revokedAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked", "expired" ] }, "redirectTo": { "type": [ "string", "null" ], "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "resendCount": { "type": "integer", "minimum": 0 }, "lastSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "SsoClientSummary": { "type": "object", "additionalProperties": false, "required": [ "id", "appId", "appKey", "clientId", "name", "environment", "status", "secretVersion", "sessionTtlSeconds", "rotatedAt", "disabledAt", "createdAt", "redirectUris" ], "properties": { "id": { "type": "string", "format": "uuid" }, "appId": { "type": "string", "format": "uuid" }, "appKey": { "type": "string" }, "clientId": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string", "enum": [ "dev", "staging", "prod" ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "secretVersion": { "type": "integer", "minimum": 1 }, "sessionTtlSeconds": { "type": "integer", "minimum": 900, "maximum": 86400 }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "redirectUris": { "type": "array", "items": { "type": "object", "required": [ "id", "redirectUri", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "redirectUri": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }