pinme-auth
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.
Install / Use
npx skills add glitternetwork/pinme --skill pinme-authInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
CommunicationSupported Platforms
Our assessment of pinme-auth
pinme-auth scores 94/100 on our quality scale, 69th of 395 Communication skills we index (top 18%).
Its SKILL.md is 10 KB long, well organised into 26 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.
With 3,760 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so pinme-auth is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-28. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
pinme-auth compared with similar skills
All 4 of these similar skills score higher than pinme-auth; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| pinme-auth (this skill)by glitternetwork | 94 | 3.8k | 2mo ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 9d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install pinme-auth?
- Run
npx skills add glitternetwork/pinme --skill pinme-auth. The install tabs above show the steps for each supported agent. - Which AI agents does pinme-auth work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is pinme-auth safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is pinme-auth still maintained?
- The repository was last updated about 2 months ago, so pinme-auth is actively maintained.
Skill content
View source on GitHubname: pinme-auth description: 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
// backend/src/worker.ts
export 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 接口的必填凭证,缺一不可。
认证方式(所有接口通用)
| 参数 | 传递方式 | 必填 | 说明 |
|------|---------|------|------|
| 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 类型
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才能通过校验。
请求体
{ "email": "alice@example.com", "password": "Test@12345678", "display_name": "Alice" }
| 字段 | 类型 | 必填 |
|------|------|------|
| 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 示例
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。
请求体
{ "id_token": "eyJh…[redacted]" }
成功响应 data
type VerifyTokenData = {
uid: string
email?: string
tenant_id: string
claims: Record<string, unknown>
}
错误
| 场景 | 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 示例
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}
错误
| 场景 | HTTP | data.error |
|------|------|-------------|
| 缺少 uid | 400 | uid is required |
| 用户不存在 | 404 | User not found |
| 上游查询失败 | 502 | Failed to get user |
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 };
}
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 示例
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…[redacted] };
}
// 批量遍历所有用户示例
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 示例
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: conf…[redacted],
authDomain: config.auth_domain,
projectId: config.auth_project_id,
})
const auth = getAuth(app)
auth.tenantId = config.tenant_id // 必须设置,确保 token 归属正确租户
return auth
}
// 邮箱密码登录,返回 id_token
export async function loginWithEmail(auth: Auth, email: string, password: string): Promise<string> {
const credential = await signInWithEmailAndPassword(auth, email, password)
return credential.user.getIdToken()
}
// Google 登录,返回 id_token
export 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.ts
import { 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 |
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
