Pinme Auth

作者 glitternetwork7822b0501607786958ecb458f3bd02a061933efa無授權條款3.7K 個星標收錄於 2026年10月9日更新於 2026年10月9日儲存庫3 週前更新

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.

僅含說明Software Development

AI 產生的概覽

指導在 PinMe Worker（TypeScript）中呼叫 PinMe 身分平台認證代理 API。

功能: 此技能說明 PinMe Worker（TypeScript）如何呼叫平台的身分平台認證代理端點：建立電子郵件密碼使用者、驗證 id_token、查詢單一使用者，以及分頁列出使用者。內容包含必要憑證（X-API-Key 標頭與 project_name 查詢參數）、共用 TypeScript 型別、請求內容、錯誤碼，以及各端點的程式碼範例。此外也說明如何使用 public_client_config 設定前端 Firebase Auth，以及典型的註冊與 Google 登入流程。
適用情境: 當 PinMe Worker 專案需要整合使用者認證時使用，例如加入電子郵件密碼註冊、驗證前端簽發的 id_token、讀取使用者資料或列舉使用者。也適用於將前端 Firebase Auth 用戶端與負責伺服器端權杖驗證的 Worker 串接。
執行需求: 執行於 PinMe Worker TypeScript 環境，需要 D1 資料庫繫結，以及環境變數 API_KEY、PROJECT_NAME 與選用的 BASE_URL，並需要連線至 PinMe API 的網路。前端整合另需 Firebase Auth SDK 與 public_client_config 中的設定值。此技能未附帶指令碼，僅包含說明與程式碼範例。

PinMe Worker Auth API Integration

Guides how to call PinMe platform's Identity Platform auth proxy APIs in a PinMe Worker (TypeScript).

Environment Variables

typescript

// backend/src/worker.tsexport interface Env {  DB: D1Database;  API_KEY: string;       // 项目 API Key — 用于所有 auth 接口认证  PROJECT_NAME: string;  // 项目名 — 所有 auth 接口必须同时传递  BASE_URL?: string;     // 可选，默认 https://pinme.cloud}

// backend/src/worker.tsexport interface Env {  DB: D1Database;  API_KEY: string;       // 项目 API Key — 用于所有 auth 接口认证  PROJECT_NAME: string;  // 项目名 — 所有 auth 接口必须同时传递  BASE_URL?: string;     // 可选，默认 https://pinme.cloud}

API_KEY 和 PROJECT_NAME 是所有 auth 接口的必填凭证，缺一不可。

认证方式（所有接口通用）

服务端会先校验这两个字段是否匹配同一个项目，再从项目配置中取出 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 类型

typescript

type ApiEnvelope<T> = {  code: number   // 200=成功，其他=失败  msg: string    // "ok" | "fail" | "invalid param"  data: T}
type ApiErrorData = { error?: string }
type UserInfo = {  uid: string  email: string  display_name: string  photo_url?: string  disabled: boolean  email_verified: boolean}

type ApiEnvelope<T> = {  code: number   // 200=成功，其他=失败  msg: string    // "ok" | "fail" | "invalid param"  data: T}
type ApiErrorData = { error?: string }
type UserInfo = {  uid: string  email: string  display_name: string  photo_url?: string  disabled: boolean  email_verified: boolean}

API 1: 创建用户

Endpoint: POST {BASE_URL}/api/v1/auth/create_user?project_name={project_name}

仅用于邮箱密码注册。成功时用户已创建且验证邮件已发出；失败时自动回滚，不会留下僵尸账号。

创建成功后用户默认仍是"未验证"状态，需点击邮件验证链接后，verify_token 才能通过校验。

请求体

错误

TypeScript 示例

typescript

async function createAuthUser(  env: Env,  payload: { email: string; password: string; display_name?: string }): Promise<{ user?: UserInfo; error?: string }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const resp = await fetch(    `${baseUrl}/api/v1/auth/create_user?project_name=${encodeURIComponent(env.PROJECT_NAME)}`,    {      method: 'POST',      headers: { 'X-API-Key': env.API_KEY, 'Content-Type': 'application/json' },      body: JSON.stringify(payload),    }  );  const result = await resp.json() as ApiEnvelope<UserInfo | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    return { error: (result.data as ApiErrorData)?.error ?? result.msg };  }  return { user: result.data as UserInfo };}

async function createAuthUser(  env: Env,  payload: { email: string; password: string; display_name?: string }): Promise<{ user?: UserInfo; error?: string }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const resp = await fetch(    `${baseUrl}/api/v1/auth/create_user?project_name=${encodeURIComponent(env.PROJECT_NAME)}`,    {      method: 'POST',      headers: { 'X-API-Key': env.API_KEY, 'Content-Type': 'application/json' },      body: JSON.stringify(payload),    }  );  const result = await resp.json() as ApiEnvelope<UserInfo | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    return { error: (result.data as ApiErrorData)?.error ?? result.msg };  }  return { user: result.data as UserInfo };}

API 2: 校验 id_token

Endpoint: POST {BASE_URL}/api/v1/auth/verify_token?project_name={project_name}

校验前端登录后拿到的 id_token（邮箱密码或 Google 登录均适用）。

注意： token 合法但邮箱未验证时返回 403，不是 401。

请求体

成功响应 data

typescript

type VerifyTokenData = {  uid: string  email?: string  tenant_id: string  claims: Record<string, unknown>}

type VerifyTokenData = {  uid: string  email?: string  tenant_id: string  claims: Record<string, unknown>}

错误

TypeScript 示例

typescript

async function verifyAuthToken(  env: Env,  idToken: string): Promise<{ uid?: string; email?: string; error?: string; emailNotVerified?: boolean }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const resp = await fetch(    `${baseUrl}/api/v1/auth/verify_token?project_name=${encodeURIComponent(env.PROJECT_NAME)}`,    {      method: 'POST',      headers: { 'X-API-Key': env.API_KEY, 'Content-Type': 'application/json' },      body: JSON.stringify({ id_token: idToken }),    }  );  const result = await resp.json() as ApiEnvelope<VerifyTokenData | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    const error = (result.data as ApiErrorData)?.error ?? result.msg;    return { error, emailNotVerified: resp.status === 403 };  }  const data = result.data as VerifyTokenData;  return { uid: data.uid, email: data.email };}

async function verifyAuthToken(  env: Env,  idToken: string): Promise<{ uid?: string; email?: string; error?: string; emailNotVerified?: boolean }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const resp = await fetch(    `${baseUrl}/api/v1/auth/verify_token?project_name=${encodeURIComponent(env.PROJECT_NAME)}`,    {      method: 'POST',      headers: { 'X-API-Key': env.API_KEY, 'Content-Type': 'application/json' },      body: JSON.stringify({ id_token: idToken }),    }  );  const result = await resp.json() as ApiEnvelope<VerifyTokenData | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    const error = (result.data as ApiErrorData)?.error ?? result.msg;    return { error, emailNotVerified: resp.status === 403 };  }  const data = result.data as VerifyTokenData;  return { uid: data.uid, email: data.email };}

API 3: 查询单个用户

Endpoint: GET {BASE_URL}/api/v1/auth/user?project_name={project_name}&uid={uid}

错误

TypeScript 示例

typescript

async function getAuthUser(env: Env, uid: string): Promise<{ user?: UserInfo; error?: string }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const resp = await fetch(    `${baseUrl}/api/v1/auth/user?project_name=${encodeURIComponent(env.PROJECT_NAME)}&uid=${encodeURIComponent(uid)}`,    { method: 'GET', headers: { 'X-API-Key': env.API_KEY } }  );  const result = await resp.json() as ApiEnvelope<UserInfo | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    return { error: (result.data as ApiErrorData)?.error ?? result.msg };  }  return { user: result.data as UserInfo };}

async function getAuthUser(env: Env, uid: string): Promise<{ user?: UserInfo; error?: string }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const resp = await fetch(    `${baseUrl}/api/v1/auth/user?project_name=${encodeURIComponent(env.PROJECT_NAME)}&uid=${encodeURIComponent(uid)}`,    { method: 'GET', headers: { 'X-API-Key': env.API_KEY } }  );  const result = await resp.json() as ApiEnvelope<UserInfo | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    return { error: (result.data as ApiErrorData)?.error ?? result.msg };  }  return { user: result.data as UserInfo };}

API 4: 列出用户（分页）

Endpoint: GET {BASE_URL}/api/v1/auth/list_users?project_name={project_name}

默认 max_results=100，最大 1000。通过 next_page_token 循环翻页。

Query 参数

TypeScript 示例

typescript

async function listAuthUsers(  env: Env,  options: { pageToken?: string; maxResults?: number } = {}): Promise<{ users?: UserInfo[]; nextPageToken?: string; error?: string }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const url = new URL('/api/v1/auth/list_users', baseUrl);  url.searchParams.set('project_name', env.PROJECT_NAME);  if (options.pageToken) url.searchParams.set('page_token', options.pageToken);  if (options.maxResults) url.searchParams.set('max_results', String(options.maxResults));
  const resp = await fetch(url.toString(), { method: 'GET', headers: { 'X-API-Key': env.API_KEY } });  const result = await resp.json() as ApiEnvelope<{ users: UserInfo[]; next_page_token?: string } | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    return { error: (result.data as ApiErrorData)?.error ?? result.msg };  }  const data = result.data as { users: UserInfo[]; next_page_token?: string };  return { users: data.users, nextPageToken: data.next_page_token };}
// 批量遍历所有用户示例async function* iterAllUsers(env: Env) {  let pageToken: string | undefined;  do {    const { users, nextPageToken, error } = await listAuthUsers(env, { pageToken, maxResults: 1000 });    if (error) throw new Error(error);    for (const user of users ?? []) yield user;    pageToken = nextPageToken;  } while (pageToken);}

async function listAuthUsers(  env: Env,  options: { pageToken?: string; maxResults?: number } = {}): Promise<{ users?: UserInfo[]; nextPageToken?: string; error?: string }> {  const baseUrl = env.BASE_URL ?? 'https://pinme.cloud';  const url = new URL('/api/v1/auth/list_users', baseUrl);  url.searchParams.set('project_name', env.PROJECT_NAME);  if (options.pageToken) url.searchParams.set('page_token', options.pageToken);  if (options.maxResults) url.searchParams.set('max_results', String(options.maxResults));
  const resp = await fetch(url.toString(), { method: 'GET', headers: { 'X-API-Key': env.API_KEY } });  const result = await resp.json() as ApiEnvelope<{ users: UserInfo[]; next_page_token?: string } | ApiErrorData>;  if (!resp.ok || result.code !== 200) {    return { error: (result.data as ApiErrorData)?.error ?? result.msg };  }  const data = result.data as { users: UserInfo[]; next_page_token?: string };  return { users: data.users, nextPageToken: data.next_page_token };}
// 批量遍历所有用户示例async function* iterAllUsers(env: Env) {  let pageToken: string | undefined;  do {    const { users, nextPageToken, error } = await listAuthUsers(env, { pageToken, maxResults: 1000 });    if (error) throw new Error(error);    for (const user of users ?? []) yield user;    pageToken = nextPageToken;  } while (pageToken);}

前端集成（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 示例

typescript

import { initializeApp } from 'firebase/app'import {  type Auth,  getAuth,  GoogleAuthProvider,  signInWithEmailAndPassword,  signInWithPopup,} from 'firebase/auth'
type PublicClientConfig = {  tenant_id: string  auth_api_key: string  auth_domain: string  auth_project_id: string}
export function createProjectAuth(config: PublicClientConfig): Auth {  const app = initializeApp({    apiKey: config.auth_api_key,    authDomain: config.auth_domain,    projectId: config.auth_project_id,  })  const auth = getAuth(app)  auth.tenantId = config.tenant_id  // 必须设置，确保 token 归属正确租户  return auth}
// 邮箱密码登录，返回 id_tokenexport async function loginWithEmail(auth: Auth, email: string, password: string): Promise<string> {  const credential = await signInWithEmailAndPassword(auth, email, password)  return credential.user.getIdToken()}
// Google 登录，返回 id_tokenexport async function loginWithGoogle(auth: Auth): Promise<string> {  const credential = await signInWithPopup(auth, new GoogleAuthProvider())  return credential.user.getIdToken()}
// 用法示例// pinme create 会自动将 public_client_config 写入 frontend/src/utils/config.tsimport { public_client_config } from '../utils/config'
const auth = createProjectAuth(public_client_config)const idToken = await loginWithGoogle(auth)// 然后把 idToken 发给自己的 Worker，由 Worker 调用 verify_token

import { initializeApp } from 'firebase/app'import {  type Auth,  getAuth,  GoogleAuthProvider,  signInWithEmailAndPassword,  signInWithPopup,} from 'firebase/auth'
type PublicClientConfig = {  tenant_id: string  auth_api_key: string  auth_domain: string  auth_project_id: string}
export function createProjectAuth(config: PublicClientConfig): Auth {  const app = initializeApp({    apiKey: config.auth_api_key,    authDomain: config.auth_domain,    projectId: config.auth_project_id,  })  const auth = getAuth(app)  auth.tenantId = config.tenant_id  // 必须设置，确保 token 归属正确租户  return auth}
// 邮箱密码登录，返回 id_tokenexport async function loginWithEmail(auth: Auth, email: string, password: string): Promise<string> {  const credential = await signInWithEmailAndPassword(auth, email, password)  return credential.user.getIdToken()}
// Google 登录，返回 id_tokenexport async function loginWithGoogle(auth: Auth): Promise<string> {  const credential = await signInWithPopup(auth, new GoogleAuthProvider())  return credential.user.getIdToken()}
// 用法示例// pinme create 会自动将 public_client_config 写入 frontend/src/utils/config.tsimport { public_client_config } from '../utils/config'
const auth = createProjectAuth(public_client_config)const idToken = await loginWithGoogle(auth)// 然后把 idToken 发给自己的 Worker，由 Worker 调用 verify_token

前端只负责登录和拿 id_token，不要直接持有项目 api_key。verify_token 必须由 Worker/服务端代调。 frontend/src/utils/config.ts 由 pinme create 自动生成，无需手动创建。

典型调用链路

邮箱密码注册流程：

create_user → 创建用户并发出验证邮件
用户点击邮件链接完成验证
前端登录拿到 id_token
verify_token → 校验 token，取得 uid
需要时再调 getAuthUser 读取完整用户信息

Google 登录流程：

前端完成 Google Sign-In，拿到 id_token
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`

來源與署名

來源：glitternetwork/pinme位於skills/pinme-auth提交7822b05

授權條款：無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

场景	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.`

场景	HTTP	`data.error`
缺少 `uid`	400	`uid is required`
用户不存在	404	`User not found`
上游查询失败	502	`Failed to get user`

Pinme Auth

PinMe Worker Auth API Integration

Environment Variables

认证方式（所有接口通用）

通用错误

通用 TypeScript 类型

API 1: 创建用户

请求体

错误

TypeScript 示例

API 2: 校验 id_token

请求体

成功响应 data

错误

TypeScript 示例

API 3: 查询单个用户

错误

TypeScript 示例

API 4: 列出用户（分页）

Query 参数

TypeScript 示例

前端集成（Firebase Auth）

两种 api_key 区分

public_client_config 字段说明

前端 TypeScript 示例

典型调用链路

易错点

來源與署名

更多來自 glitternetwork/pinme 的技能

Pinme Llm

Pinme Email

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

字段	类型	必填
`email`	string	是
`password`	string	是
`display_name`	string	否

场景	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.`

参数	必填	说明
`project_name`	是	项目名
`page_token`	否	分页游标
`max_results`	否	每页数量，1–1000