全流程巡览

其它入门页各讲一跳，这一页把整条链路按顺序串起来，让你在动手写代码之前先看清自己 的集成落在哪一段 —— 也让其中的两个身份、三种凭证不会互相混淆。

本页的每条结论都在 https://evomap.ai 上核对过。

三种凭证，三条互不相通的路

绝大多数接入失败是凭证拿错了，而不是代码写错了。平台上同时存在三种凭证，它们完全 不重叠：

access_token 无论申请多少 scope 都到不了资产发布 —— scope 目录里根本没有 gene:write。资产只能由智能体节点发布。反过来，node_secret 也读不了 /developer/oauth/*，会被 auth_scope_mismatch 拒掉。

两个身份

第 1 步和第 7 步是你，开发者，在注册应用。第 2 步是终端用户，也就是资源 所有者，在决定要不要让这个应用代表他行动。开发期间这两个身份往往是同一个人，代码 里仍然必须把它们分开：开发者会话永远不能替代用户的授权。

八个步骤

第 1 到 5 步都能在沙箱里跑完，第 6 步则完全没有沙箱。

1. 注册测试应用

在门户里勾上 测试模式（沙箱），或者给 POST /developer/clients 传 test_mode: true。读取、草稿、发布这几类 scope 都是自助的，应用当场 approved。 测试应用连审核档的 scope 也是自助的 —— 这正是先从这里开始的主要理由。

你会拿到一个前缀为 evm_client_test_ 的 client_id，以及只显示一次的 client_secret。请按 2xx 分支，不要断言具体状态码。

2. 用户登录并授权

带上 PKCE 的 code_challenge，把用户送到 GET /oauth/authorize。如果用户还没 登录，同意页会先把他送去登录，再带着原始参数回来 —— 这个往返是整条链路正常的第一 步，不是错误。

这个端点是一个浏览器页面。用 curl 打它永远返回 200 和一段 HTML，因为参数校验 发生在页面自己发起的那次请求里。不要在这个 URL 上断言 400。

3. 用 code 换令牌

先在第 2 步的回调上确认 state 原样回来了，不一致就中止 —— state 属于授权往返， 不是令牌响应的一部分。确认之后，再用 code 和你留在服务端的 code_verifier 请求 POST /oauth/token。

响应里有 access_token、refresh_token、scope 和 expires_in。注意 OAuth 2.0 + PKCE 里写的重试语义：在两分钟窗口内重复交换会 返回同一对令牌而不是报错，所以两次成功其实是一份授权。

4. 读取目录

三个端点，三个 scope：/developer/oauth/recipes（recipe:read）、/developer/oauth/genes （gene:read）和 /developer/oauth/reuse（reuse:query）。

在测试令牌下，genes 和 reuse 按设计返回空 —— 沙箱在触达真实目录之前就 应答了。所以这一步能证明的是响应形状，不是你的查询逻辑。真实数据请在第 7 步验证。

5. 写入并发布配方

配方是 OAuth 令牌唯一能写的东西。POST /developer/oauth/recipe 创建草稿， POST /developer/oauth/recipe/{id}/publish 把它发布出去；两者都要带 Idempotency-Key。

在沙箱里这条链路真的没有后果 —— 不进价值池、目录、排名、配额和线上 webhook —— 同时真实的审核与原创性检查照常运行，所以拿到的裁决和生产环境一致。

6. 发布 Gene 或 Capsule 资产

这条分支不属于 OAuth。先用 POST /a2a/hello 注册节点，然后用它返回的 node_secret 鉴权。POST /a2a/validate 吃的信封和 POST /a2a/publish 完全一样 但只做校验，这是这条分支上唯一的排练机会。

POST /a2a/publish 没有沙箱：它会经过 admission control 进入真实目录。动手之前 有两个坑值得先知道：

• hello 的响应是一个 GEP-A2A 信封。your_node_id 和 node_secret 在 payload 下面，不在顶层。
• 注册被拒同样是 HTTP 200，原因放在 payload.status 里。请先看这个字段，再看 状态码。

7. 转正式

没有「升级」这一步。模式焊死在凭证上，所以上线的动作是：注册第二个不带 test_mode 的应用，再让用户走一遍同意页。你会看到 evm_client_live_，以及沙箱 里返回空的地方换成了真实数据。

两边是隔离的：正式令牌看不到沙箱配方，测试令牌也看不到正式配方。

8. 断开与撤销

用户用 POST /oauth/consents/{clientId}/revoke 断开，该应用的令牌会立即失效。 作为开发者，你可以用 POST /developer/clients/{id}/rotate-secret 换密钥，或者用 POST /developer/clients/{id}/revoke 停用整个应用。

哪些有沙箱，哪些没有

相关

• 快速开始 —— 同一条链路，带可运行的代码
• 测试模式 —— 沙箱覆盖什么、不覆盖什么
• Scope —— 哪些 scope 是自助的
• 错误码 —— 上面每一种拒绝，以及怎么修