开始使用

鉴权与权限

REST API 只认一种凭证:工作区管理员在设置页签发的长期 Bearer 凭证。它代表整个工作区,权限在签发时就钉死 —— scope 决定能调哪些端点,发布落点决定内容最远能推到哪一档。

怎么带凭证

Authorization: Bearer popkit_it_••••••••

每个请求都带这个头。凭证以 popkit_it_ 开头;没带、拼错、已停用、已过期都回 401(unauthenticated),并带 WWW-Authenticate: Bearer realm="popkit-api"。不要把凭证放进前端代码、公开仓库或 URL。

OAuth 访问令牌(AI 客户端经授权页拿到的那种)在这里不能用,它们属于 MCP 端点。两条路的能力一致,只是面向的调用方不同。

凭证缺少端点要求的 scope 时回 403(forbidden,params.scope 说明缺哪个)。签发者的工作区角色同样要允许该动作 —— scope 只能收窄,不能越过角色矩阵。

scope	含义	端点
workspace:read	工作区信息、成员数与配额余量	GET /workspace
accounts:read	已连接的社交账号与授权状态	GET /accounts
posts:read	草稿、排期与发布记录	GET /posts、GET /posts/{postId}、POST /posts/precheck
posts:write	创建和修改草稿、上传媒体	POST /posts、PATCH /posts/{postId}、POST /posts/{postId}/reschedule、POST /posts/{postId}/cover-suggestions、POST /posts/{postId}/cover、POST /media
approvals:write	把草稿提交审批	POST /posts/{postId}/submit
schedule:write	安排定时发布	POST /posts、PATCH /posts/{postId}、POST /posts/{postId}/reschedule、POST /posts/{postId}/publish
publish:execute	立即对外发布内容	POST /posts、PATCH /posts/{postId}、POST /posts/{postId}/confirm、POST /posts/{postId}/publish
comments:read	查看已发布内容收到的评论	GET /comments
comments:write	以工作区的社交账号回复评论	POST /comments/{commentId}/replies
analytics:read	数据指标与趋势	GET /analytics/summary
ideas:read	查看选题库	GET /ideas
ideas:write	往选题库写入选题	POST /ideas、PATCH /ideas/{ideaId}

写内容的端点用 action 决定落点:draft 存草稿、schedule 定时、publish 立即外发。凭证签发时逐档勾选,默认一档都不给;请求的档位不在白名单里回 403(params.action)。

长期凭证默认是预授权模式(无人值守,action: "publish" 一步到位)。若凭证被设为两步确认,新建 / 修改会先落草稿并回 confirm.token,十分钟内调确认发布才真正外发。响应里有没有 confirm 字段就是判断依据。