自动化 OrbitPage,无需共享仪表板会话。
创建范围令牌并从脚本、n8n、后端或 CI 端到端管理 OrbitPage 仪表板。
最新修订:2026年8月4日使用受限个人令牌管理 OrbitPage 工作区:编辑和发布页面,并使用媒体、域名、分析、AI、Shop、新闻通讯和账单功能。
三个凭证边界涵盖三个不同的工作。
此页面记录了版本化的 REST 边界。 OrbitPage 令牌不是 OpenAI 提供商密钥,并且从不验证私有仪表板端点。
| 表面 | 凭证 | 目的和支持 |
|---|---|---|
| 自动化 REST API | op_pat_... | 支持脚本、n8n、服务器后端和 CI 的外部 API。它通过 /api/v1 管理令牌绑定的工作区。 |
| OrbitPage AI | op_pat_... + ai:read/ai:write | 公共计划/提交流程准备并应用经过验证的人工智能提案。任何 OpenAI 提供商凭证仍然是一个单独的服务器端问题,并且永远不是 OrbitPage 不记名令牌。 |
| 仪表板 API | SaaS 上的 Firebase 会话; OSS 上的管理会话 | 私有浏览器到应用程序的路由。它们不是稳定的外部集成合约,不得接收个人 API 代币。 |
版本化资源涵盖仪表板;链接端点显示安全更新循环。
每个请求都绑定到创建令牌时选择的工作区。令牌无法在 URL 或请求正文中选择其他租户,并且每次调用时都会再次检查当前工作区权限。
该合约使用标准 HTTPS JSON 操作——GET、POST、PUT、PATCH 和 DELETE——并支持curl、n8n 的 HTTP 请求节点和生成的 OpenAPI 客户端。
GET/api/v1/links读取每个页块
返回有序集合、工作区标识和当前修订。
范围:links:readPATCH/api/v1/links/{linkId}更改一个现有块
合并可编辑字段,验证整个页面并发布新修订版。
范围:links:writePUT/api/v1/links替换完整集合
使用它在读取和保留当前集合后添加、删除或重新排序块。
范围:links:write| 仪表板表面 | API 路径 | 范围 |
|---|---|---|
| 工作区和完整草稿 | /workspace · /draft | workspace:read |
| 简介、主题和子页面 | /profile · /theme · /pages | profile:* · theme:* · pages:* |
| 一般、隐私和菜单设置 | /settings/* | settings:* |
| 发布、版本和备份 | /publication · /versions · /backup | publication:* · backup:* |
| 媒体和自定义域 | /media/* · /domains/* | media:* · domains:* |
| 分析和审查人工智能变化 | /analytics · /ai/* | analytics:read · ai:* |
| 商店和时事通讯 | /shop/* · /newsletter/* | shop:* · newsletter:* |
| 团队和计费 | /team/* · /billing/* | team:* · billing:* |
每个支持的仪表板操作,按其控制的表面分组。
以下路径以 https://orbitpage.com/api/v1 为基准。方法、路径和权限范围是稳定的集成契约;请求架构、格式、枚举值和响应模型位于链接的 OpenAPI 3.1 文档中。未知路由返回 404,不支持的方法绝不会被静默转换。
01工作空间、内容和外观检查令牌绑定工作区并管理其完整的草稿、配置文件、块、主题和子页面。11 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/workspace | 阅读工作空间、计划、访问、使用和修订 | workspace:read | — |
GET/draft | 阅读完整的可编辑页面草稿 | workspace:read | — |
GET/links | 列出页面块和当前版本 | links:read | — |
PUT/links | 替换完整的有序块集合 | links:write | LinksReplaceRequest · If-Match |
PATCH/links/{linkId} | 更新一个块上的可编辑字段 | links:write | LinkPatch · If-Match |
GET/profile | 读取个人资料身份和元数据 | profile:read | — |
PATCH/profile | 更新个人资料字段 | profile:write | JSON · If-Match · ?publish=1 |
GET/theme | 阅读活动草稿主题 | theme:read | — |
PUT/theme | 替换草稿主题 | theme:write | JSON · If-Match · ?publish=1 |
GET/pages | 列出配置的子页面 | pages:read | — |
PUT/pages | 替换配置的子页面 | pages:write | array | { pages } · If-Match · ?publish=1 |
02设置和发布控制菜单、隐私、托管公共文件、站点地图生成和明确的草稿公开生命周期。9 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/settings | 读取菜单、隐私、文本文件和站点地图设置 | settings:read | — |
PUT/settings/menu | 更新菜单设置 | settings:write | JSON · If-Match · ?publish=1 |
PUT/settings/privacy | 更新同意和隐私设置 | settings:write | JSON · If-Match · ?publish=1 |
POST/settings/text-files | 创建托管公共文本文件 | settings:write | TextFileCreateRequest · If-Match |
PUT/settings/text-files/{key} | 更新托管公共文本文件 | settings:write | TextFileUpdateRequest · If-Match |
DELETE/settings/text-files/{key} | 删除托管公共文本文件 | settings:write | If-Match |
POST/settings/sitemap | 重新生成托管站点地图 | settings:write | If-Match |
GET/publication | 阅读草稿和发布状态 | publication:read | — |
POST/publication | 发布最新的经过验证的草稿 | publication:write | — |
03版本、备份和媒体恢复修订内容、导出或导入工作区数据以及运行保留-上传-最终确定媒体生命周期。9 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/versions | 列出可恢复的已发布页面版本 | backup:read | — |
POST/versions/{revision}/restore | 恢复并立即发布历史版本 | backup:write | If-Match |
GET/backup | 导出托管工作区备份 | backup:read | ?sections=profile,links,… |
POST/backup/restore | 验证、恢复并立即发布托管备份 | backup:write | BackupRestoreRequest · If-Match |
GET/media | 列出工作区媒体元数据和使用情况 | media:read | — |
POST/media/cleanup | 预览或删除未引用的媒体 | media:write | MediaCleanupRequest |
POST/media/uploads/reserve | 保留直接媒体上传 | media:write | MediaUploadReserveRequest |
POST/media/uploads/finalize | 最终确定并注册上传的对象 | media:write | UploadTokenRequest |
DELETE/media/uploads | 中止保留的媒体上传 | media:write | UploadTokenRequest |
04领域、分析和人工智能管理 DNS 激活、读取计划范围内的性能报告并仅在经过验证的预览后应用 AI 更改。8 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/domains | 读取域状态和 DNS 要求 | domains:read | — |
POST/domains | 连接自定义域 | domains:write | DomainConnectRequest |
POST/domains/refresh | 刷新验证并激活 | domains:write | — |
DELETE/domains | 断开自定义域 | domains:write | — |
GET/analytics | 阅读仪表板分析报告 | analytics:read | ?days=7|30|90 |
GET/ai/allowance | 读取AI限额和当前使用情况 | ai:read | — |
POST/ai/plan | 生成经过验证的 AI 更改预览 | ai:write | AiPlanRequest |
POST/ai/commit | 提交之前验证的 AI 预览 | ai:write | AiCommitRequest |
05Shop连接商务、管理产品和外观、上传受保护的文件,然后发布或取消发布同步的商店块。10 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/shop | 读取产品、订单、客户和 Shop 状态;该操作可能初始化 Shop 私有数据并刷新 Stripe 状态 | shop:read | ?refresh=0|1 |
POST/shop/connect | 创建或继续 Stripe Connect 入门 | shop:write | — |
POST/shop/products | 创建或更新商店产品 | shop:write | ShopProductRequest |
DELETE/shop/products/{productId} | 删除商店产品 | shop:write | — |
PUT/shop/appearance | 替换整个商店外观 | shop:write | ShopAppearanceRequest |
POST/shop/publish | 发布 Shop 及其同步页面区块 | shop:write | — |
POST/shop/unpublish | 取消发布商店 | shop:write | — |
POST/shop/uploads/reserve | 保留产品文件上传 | shop:write | ShopFileUploadReserveRequest |
POST/shop/uploads/finalize | 完成产品文件上传 | shop:write | ShopUploadTokenRequest |
DELETE/shop/uploads | 取消已预留的产品文件上传 | shop:write | ShopUploadTokenRequest |
06时事通讯配置加密 SMTP 传送、管理同意的订阅者并控制整个活动生命周期。9 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/newsletter | 读取订阅者、活动和 SMTP 状态 | newsletter:read | — |
PUT/newsletter/settings | 更新加密的 SMTP 设置 | newsletter:write | NewsletterSmtpRequest |
POST/newsletter/settings/test | 发送配置测试 | newsletter:write | EmailRecipientRequest |
POST/newsletter/subscribers | 添加或更新同意的订户 | newsletter:write | NewsletterSubscriberRequest |
DELETE/newsletter/subscribers/{subscriberId} | 删除订阅者 | newsletter:write | — |
POST/newsletter/campaigns | 创建或更新营销活动 | newsletter:write | NewsletterCampaignRequest |
DELETE/newsletter/campaigns/{campaignId} | 删除营销活动 | newsletter:write | — |
POST/newsletter/campaigns/{campaignId}/send | 排队或安排活动 | newsletter:write | NewsletterSendRequest |
DELETE/newsletter/campaigns/{campaignId}/send | 取消排队的活动 | newsletter:write | — |
07团队和计费管理协作者和邀请、检查订阅并打开经过身份验证的 Stripe 结帐或门户会话。9 操作
| 方法和路径 | 操作 | 所需范围 | 输入和控制 |
|---|---|---|---|
GET/team | 列出成员和待处理的邀请 | team:read | — |
POST/team/invitations | 创建工作区邀请链接而不发送电子邮件 | team:write | TeamInvitationRequest |
PATCH/team/members/{memberUid} | 更新成员角色 | team:write | TeamRoleRequest |
DELETE/team/members/{memberUid} | 删除工作区成员 | team:write | — |
DELETE/team/invitations/{invitationId} | 撤销待处理的邀请 | team:write | — |
GET/billing | 读取计划和订阅状态 | billing:read | — |
POST/billing/checkout | 创建 Stripe 计划结账 | billing:write | BillingCheckoutRequest |
POST/billing/portal | 创建 Stripe 计费门户会话 | billing:write | BillingPortalRequest |
POST/billing/promotion-code | 兑换促销代码并重新核对套餐权益 | billing:write | PromotionCodeRedeemRequest |
为一种自动化和一种环境创建一种令牌。
打开仪表板 > 帐户 > 个人 API 令牌。为令牌指定一个可识别其所有者和用途的名称,选择完整工作区、只读工作区、仅链接或单个资源范围,然后选择 30、90 或 365 天的到期日,或者在记录的轮换过程已存在时选择无到期日。
确认您的身份
令牌创建是一项敏感帐户操作,需要最近的 Google 或密码身份验证。
选择最小范围
每个资源的读取和写入范围是分开的 - 例如 theme:read, theme:write, shop:read 和 shop:write. 写入范围自动包含其匹配的读取范围。
复制密码一次
OrbitPage 存储 SHA-256 哈希值,而不是可恢复的机密。如果丢失,则撤销它并创建另一个令牌。
将其存储在代码之外
使用环境变量或 CI 秘密存储。切勿将令牌放入 URL、存储库、屏幕截图、浏览器捆绑包或构建日志中。
export ORBITPAGE_TOKEN='op_pat_...'
curl --silent --show-error --include \
--header "Authorization: Bearer $ORBITPAGE_TOKEN" \
https://orbitpage.com/api/v1/links$env:ORBITPAGE_TOKEN = 'op_pat_...'
$headers = @{ Authorization = "Bearer $env:ORBITPAGE_TOKEN" }
Invoke-RestMethod -Uri 'https://orbitpage.com/api/v1/links' -Headers $headers在每次更改之前阅读集合并捕获其修订版本。
响应正文包含数据中的有序块和当前数字修订版。相同的修订版出现在 X-OrbitPage-Revision 中并作为弱 ETag。保存 If-Match 的任一值;不要在不相关的运行中猜测或缓存它。
HTTP/2 200
etag: W/"42"
x-orbitpage-revision: 42
content-type: application/json; charset=utf-8
{
"object": "list",
"data": [
{
"id": "portfolio-main",
"type": "link",
"title": "Selected work",
"description": "Recent projects and case studies",
"url": "https://example.com/work",
"isActive": true,
"status": "live",
"availability": "available",
"clickCount": 18,
"position": 0
}
],
"revision": 42,
"workspace": {
"tenantId": "tenant_...",
"pageId": "page_...",
"username": "your-page"
}
}data完整的有序块集合。数组顺序是视觉页面顺序。revision每次写入使用的乐观并发版本。workspace永久绑定到此令牌的租户、页面和用户名。ETag作为下一个 If-Match 标头直接传递的最安全值。使用 PATCH 对现有块进行最小的更改。
对 GET 返回的 ID 进行 URL 编码,并仅发送应更改的字段。 OrbitPage 将补丁合并到现有块中,保护身份和分析字段,根据其架构和计划验证完整页面,然后立即发布。
curl --request PATCH \
--url https://orbitpage.com/api/v1/links/portfolio-main \
--header "Authorization: Bearer $ORBITPAGE_TOKEN" \
--header 'Content-Type: application/json' \
--header 'If-Match: W/"42"' \
--data '{
"title": "Book a consultation",
"url": "https://example.com/book",
"isActive": true
}'| 字段组 | 示例 | 行为 |
|---|---|---|
| 内容 | title, description, url, content, textItems | 对现有块类型有效时可编辑。 |
| 可见性和时间安排 | isActive, status, availability, startDate, endDate, timezone | 与调度和计划规则一起验证。 |
| 外观和媒体 | icon, coverImage, backgroundColor, alignment, size | 仅当值与页面架构匹配时才接受。 |
| 受保护 | id, type, clickCount, ctaClicks, systemKey | 被忽略或拒绝。系统管理的块无法修补。 |
仅当集合本身必须更改时才使用 PUT。
PUT 替换完整的有序集合。它是添加块、删除块或更改页顺序的操作。它不是更新一个标题的快捷方式:省略一个块会将其从页面中删除。
const token = process.env.ORBITPAGE_TOKEN;
if (!token) throw new Error("ORBITPAGE_TOKEN is missing");
const endpoint = "https://orbitpage.com/api/v1/links";
const authorization = { Authorization: `Bearer ${token}` };
const read = await fetch(endpoint, { headers: authorization });
if (!read.ok) throw new Error(`GET failed: ${read.status} ${await read.text()}`);
const current = await read.json();
const revision = read.headers.get("etag") ?? String(current.revision);
// Preserve the full collection and change only the intended block.
const links = current.data.map((block) =>
block.id === "portfolio-main"
? { ...block, title: "Work and case studies" }
: block
);
const write = await fetch(endpoint, {
method: "PUT",
headers: {
...authorization,
"Content-Type": "application/json",
"If-Match": revision
},
body: JSON.stringify({ links })
});
if (!write.ok) throw new Error(`PUT failed: ${write.status} ${await write.text()}`);
console.log(await write.json());使用本机 n8n 节点或来自 HTTP 客户端、生成的客户端、后端或 CI 运行程序的相同合约。
OrbitPage 不需要 SDK:任何可以发送 JSON、Bearer 身份验证和标准 GET、POST、PUT、PATCH 和 DELETE 请求的 HTTPS 客户端都是兼容的。下面的模式涵盖了集成必须显式处理的有状态部分。
原生 n8n 节点
安装 n8n-nodes-orbitpage,并使用个人令牌和 Base URL 创建 OrbitPage API 凭据。连接测试会安全读取工作区;随后,引导式操作会处理路径、权限、项目关联和带修订控制的写入,且不会把密钥保存到工作流 JSON 中。
草案和发布
配置文件、主题、页面和支持的设置默认写入需要 If-Match 并更新草稿。添加 ?publish=1 以获得符合条件的立即发布,或查看几个延迟的更改并调用 POST /publication 一次。链接 PATCH 和 PUT 立即发布。
直接媒体上传
先预留上传,将数据发送到返回的存储 URL,然后完成操作。OrbitPage bearer token 只能发送到 orbitpage.com;存储请求只能使用返回的方法和临时标头。
审查了 AI 提交
计划返回经过验证的预览,而不改变页面。存储并查看其previewToken,然后准确提交该提案。仅当自动化被授权公开结果时,才在提交正文中设置发布。
Install community node: n8n-nodes-orbitpage
Credential: OrbitPage API
OrbitPage API Token: op_pat_...
OrbitPage Base URL: https://orbitpage.com
Connection test: GET /api/v1/workspace
First safe workflow step:
Node: OrbitPage
Resource: Workspace & Draft
Operation: Get Workspace Overview
First revision-controlled write:
Resource: Theme
Operation: Replace Entire Theme Draft
Revision Check: Use Latest Automatically (Recommended)# 1. Reserve an upload and receive uploadUrl, slot and uploadToken
POST /api/v1/media/uploads/reserve
{ "filename": "cover.jpg", "contentType": "image/jpeg", "sizeBytes": 245760 }
# 2. Upload the bytes directly using the returned URL, method and headers
# Do not forward the OrbitPage Authorization header to the storage URL.
# 3. Register the uploaded object in the workspace
POST /api/v1/media/uploads/finalize
{ "slot": "<slot>", "uploadToken": "<uploadToken>" }# 1. Generate a validated preview without changing the page
POST /api/v1/ai/plan
{ "message": "Make the primary CTA clearer" }
# 2. Review the returned operations and previewToken
# 3. Apply the exact reviewed preview; publishing remains explicit
POST /api/v1/ai/commit
{ "previewToken": "<previewToken>", "publish": false }将 https://orbitpage.com 用作 Base URL,不要附加 /api/v1。成功保存时会读取 /api/v1/workspace,并在不更改数据的情况下验证令牌、工作区绑定和 workspace:read 权限。
401 错误需要有效的替换令牌,403 错误表示缺少权限。若反复发生重定向,请检查 Base URL 或反向代理。向支持团队提供状态和 JSON 代码,但绝不要提供密钥。
将自动化凭证视为短暂的、可观察的生命周期。
工作区支持每个用户最多 10 个活动个人令牌。帐户列表显示每个令牌的前缀、范围、创建和到期日期以及最近的使用情况。最后使用的时间戳最多每五分钟写入一次。
name: Update OrbitPage
on: workflow_dispatch
jobs:
update:
runs-on: ubuntu-latest
env:
ORBITPAGE_TOKEN: ${{ secrets.ORBITPAGE_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: node scripts/update-orbitpage.mjs- 按系统和环境命名令牌 - 例如,“GitHub Actions · production”。
- 通过创建替换、更新秘密存储、测试一次读取、然后撤销旧令牌来轮换。
- 在涉嫌披露、所有权变更或工作流程停用后立即撤销。撤销在下一次请求时生效。
- 不要构建长期共享令牌。单独的凭据使日志、轮换和事件响应易于理解。
HTTP 状态和机器可读代码的分支。
错误使用带有错误和代码的 JSON。不要解析人类句子来控制工作流程。大多数 4xx 响应需要更改请求或凭据;只有修订冲突和速率限制属于自动重试路径。
INVALID_JSON · LINKS_REQUIRED · LINK_PATCH_INVALID修复页面架构拒绝的请求正文或字段。PERSONAL_TOKEN_*替换丢失、无效、过期或撤销的令牌。不要使用相同的密码重试。PERSONAL_TOKEN_SCOPE_DENIED · SYSTEM_LINK_PROTECTED使用所需范围或停止:当前身份不允许执行此操作。LINK_NOT_FOUND刷新收藏;块 ID 可能已被删除或替换。revision_conflict再次执行 GET,将预期更改重新应用到新状态,并使用新修订号重试。REQUEST_TOO_LARGE将 JSON 正文保持在 768 KiB 或以下。UNSUPPORTED_CONTENT_ENCODING发送未压缩的 JSON 请求正文。revision_required使用最新 GET 返回的修订版或 ETag 添加 If-Match。RATE_LIMITED等待 Retry-After 指定的时间,然后使用指数退避和随机抖动重试。当前限制为每个令牌每分钟 120 个请求、每天 5,000 个请求。滥用防护可能收紧限制;请始终遵循 Retry-After。
安全集成是狭窄的、秘密的和修订感知的。
最低权限
使用只读,除非作业必须发布。令牌功能永远不能超出所有者当前的工作区角色。
仅服务器端
从受信任的脚本、后端或 CI 运行程序调用 API。浏览器捆绑包、移动客户端或公共存储库无法保守承载秘密。
禁止盲写
请在写入前立即执行 GET 请求并使用 If-Match。如果 409 错误返回 revision_conflict,请重新读取资源并再次应用预期更改;对于其他错误代码,请解决文档所述的业务条件。
验证结果
检查响应状态、修订和返回的数据。对于重要更改,请在发布后打开公共页面并在失败时发出警报,而无需记录令牌。
个人令牌自动化 REST API 是一种托管 SaaS 功能。
开源仓库包含内置仪表板使用的 Express API,但该内部管理员会话 API 不是同一个版本化自动化契约。不要把 op_pat 令牌发送到自托管服务器,也不要把自托管管理员 JWT 发送到 orbitpage.com/api/v1。
使用本指南、OpenAPI 合约和在帐户中创建的个人代币。
使用同一受信任源上的捆绑仪表板。存储库文档解释了贡献者和维护者的内部边界。