Use when a PinMe project (Worker TypeScript) needs to integrate user authentication — creating email/password users, verifying id_tokens, querying user info, or listing users via Identity Platform auth proxy APIs.

PinMe Worker Auth API Integration Guides how to call PinMe platform's Identity Platform auth proxy APIs in a PinMe Worker (TypeScript). Environment Variables API KEY 和 PROJECT NAME 是所有 auth 接口的必填凭证，缺一不可。认证方式（所有接口通用）参数传递方式必填说明 X API Key 请求头是项目 API Key project name Query 参数是必须与 X API Key 对应同一个项目服务端会先校验这两个字段是否匹配同一个项目，再从项目配置中取出 tenant id ，然后转调 Identity Platform。通用错误场景 HTTP data.error 缺少 X API Key 401 X API Key header is required 缺少 project name 400 project name is required API Key 和项目不匹配 401 Invalid API key or project name 项目未配置认证租户 400 Auth service not configured for this project 通用 TypeScript 类型 API 1: 创建用户 Endpoint: POST {BASE URL}/api/v1/auth/create user?project name={project name} 仅用于邮箱密码注册。成功时用户已创建且验证邮件已发出；失败时自动回滚，不会留下僵尸账号。创建成功后用户默认仍是"未验证"状态，需点击邮件验证链接后， verify token 才能通过校验。请求体字段类型必填 email string 是 password string 是 display name string 否错误场景 HTTP data.error 缺少 email/password 400 email and password are required 上游创建失败 502 Failed to create user 发送验证邮件失败 500 Failed to send verification email. Please try again. TypeScript 示例 API 2: 校验 id token Endpoint: POST {BASE URL}/api/v1/auth/verify token?project name={project name} 校验前端登录后拿到的 id token （邮箱密码或 Google 登录均适用）。注意： token 合法但邮箱未验证时返回 403 ，不是 401 。请求体成功响应 data 错误场景 HTTP data.error 缺少 id token 400 id token is required token 无效或过期 401 Invalid or expired token 邮箱未验证 403 Email not verified. Please check your inbox and verify your email address. TypeScript 示例 API 3: 查询单个用户 Endpoint: GET {BASE URL}/api/v1/auth/user?project name={project name}&uid={uid} 错误场景 HTTP data.error 缺少 uid 400 uid is required 用户不存在 404 User not found 上游查询失败 502 Failed to get user TypeScript 示例 API 4: 列出用户（分页） Endpoint: GET {BASE URL}/api/v1/auth/list users?project name={project name} 默认 max results=100 ，最大 1000 。通过 next page token 循环翻页。 Query 参数参数必填说明 project name 是项目名 page token 否分页游标 max results 否每页数量，1–1000 TypeScript 示例前端集成（Firebase Auth） create worker 响应中包含 public client config ，前端用它初始化 Firebase Auth SDK。两种 api key 区分字段用途是否可暴露到浏览器 data.api key 项目 API Key，调用本文所有代理接口不能，只给 Worker/服务端 data.public client config.auth api key Firebase Web API Key，初始化前端登录 SDK 可以 public client config 字段说明字段前端用途 public client config.auth api key initializeApp({ apiKey }) public client config.auth domain initializeApp({ authDomain }) public client config.auth project id initializeApp({ projectId }) public client config.tenant id auth.tenantId = config.tenant id （必须设置，否则 token 归属错误）前端 TypeScript 示例前端只负责登录和拿 id token ，不要直接持有项目 api key 。 verify token 必须由 Worker/服务端代调。 frontend/src/utils/config.ts 由 pinme create 自动生成，无需手动创建。典型调用链路邮箱密码注册流程： 1. create user → 创建用户并发出验证邮件 2. 用户点击邮件链接完成验证 3. 前端登录拿到 id token 4. verify token → 校验 token，取得 uid 5. 需要时再调 getAuthUser 读取完整用户信息 Google 登录流程： 1. 前端完成 Google Sign In，拿到 id token 2. verify token → 校验 token（无需调用 create user ）易错点错误正确做法只传 X API Key ，忘记 project name 每个请求都要同时带 X API Key header 和 project name query verify token 返回 403 时当 token 失效处理 403 = 邮箱未验证，提示用户检查邮箱；401 才是 token 失效 create user 成功就认为邮箱已验证创建成功只代表验证邮件已发，用户必须点击后才算验证 list users 只取第一页有 next page token 时需继续请求，直到为空成功判断只看 resp.ok 同时判断 resp.ok && result.code === 200

pinme-auth