Composio YNAB Toolkit 认证完全指南：托管 OAuth 与客户自持 OAuth 的配置与审核处理

YNAB（You Need A Budget）是知名的个人预算管理工具，Composio 通过其 YNAB toolkit 为 AI Agent 提供预算、账户、分类、交易等 27 个工具能力。本文基于 Composio 仓库中的 YNAB 认证文档，系统讲解两条 OAuth 接入路径——Composio 托管 OAuth 与客户自持 OAuth——的适用场景、配置步骤、redirect URI 注册要点，以及 YNAB 应用审核限制的应对方法，帮助你在 Agent 中快速、合规地接入 YNAB 数据。

YNAB Toolkit 概览：OAUTH2 是唯一认证方案

在进入认证配置之前，先确认 YNAB toolkit 的基本事实。根据仓库中的工具清单数据 docs/public/data/toolkits.json，YNAB toolkit 的元数据如下：

• slug：ynab
• 分类：accounting（会计/财务管理）
• 认证方案（authSchemes）：OAUTH2
• Composio 托管认证方案（composioManagedAuthSchemes）：OAUTH2
• 工具数量：27 个，触发器数量 0
• 版本：20260721_00（以仓库当前数据为准）

OAUTH2 意味着 YNAB 走的是 OAuth 2.0 授权码流程（authorization-code flow），且 Composio 官方托管认证同样支持该方案。同时，CLI 端生成的 toolkit-slugs.ts 中也包含 'ynab' slug，说明 YNAB toolkit 已纳入 CLI 的 toolkit 管理流程。

从工具清单可以看出，该 toolkit 覆盖了预算的读写操作，例如 YNAB_CREATE_ACCOUNT（在预算中创建账户）、YNAB_GET_BUDGET_BY_ID（获取完整预算导出，含账户、分类、收款人、交易）、YNAB_CREATE_SCHEDULED_TRANSACTION（创建周期性交易）、YNAB_GET_USER（获取已授权用户信息）等。这些工具全部依赖 OAuth 连接完成鉴权，因此认证配置是该 toolkit 一切能力的前提。

两条 OAuth 接入路径：托管认证与客户自持认证

仓库中的官方认证指南 docs/kb/articles/toolkits-ynab.md（其知识库来源为 docs/kb/source/toolkits/ynab/public.md，站点版本见 docs/content/kb/guide/toolkits-ynab.mdx）明确指出：

YNAB supports managed and customer-owned OAuth.

这句话定义了接入 YNAB 的两种模式：

模式	适用场景	关键动作
Composio 托管 OAuth（managed OAuth）	标准连接流程，绝大多数集成场景	使用 Composio 内置的 YNAB OAuth 应用，无需自备凭据
客户自持 OAuth（customer-owned OAuth）	客户需要对 provider 应用拥有控制权	创建自定义 auth config，填入客户自己的 YNAB client ID 与 client secret

这一分法与 Composio 平台层 "managed vs custom auth" 的整体设计一致。平台文档 docs/api-overviews/auth-configs.mdx 中对 OAUTH2 方案的说明为：用户通过托管 consent 页面完成授权，Composio 存储并自动刷新 access token 与 refresh token；默认使用 Composio 的托管 OAuth 应用，也可自带应用以实现自定义品牌或自定义 scope。当需要自有品牌的授权页面、自定义 scope、独立限流配额或自定义 toolkit 实例时，应选用自定义 auth config。

路径一：使用 Composio 托管 OAuth（推荐用于标准流程）

对于大多数 YNAB 集成需求，直接使用 Composio 托管 OAuth 即可。用户通过 Composio 的托管授权流程完成 YNAB 登录与授权，Composio 负责令牌的存储与后台自动刷新，接入方无需接触 YNAB 开发者平台的任何配置。

在 Python SDK 中，创建一个使用 Composio 托管认证的 auth config 非常简单，参考 python/examples/auth_configs.py 的写法：

from composio import Composio

composio = Composio()

# 使用 Composio 托管认证
auth_config = composio.auth_configs.create(
    toolkit="ynab",
    options={
        "type": "use_composio_managed_auth",
    },
)
print(auth_config)

创建完成后，即可基于该 auth config 建立 connected account，随后调用 YNAB toolkit 下的 27 个工具。

路径二：创建客户自持 OAuth（customer-owned OAuth）

当客户需要完全掌控 YNAB 开发者应用（例如需要自定义授权页品牌、申请额外 scope、或企业内部要求应用归属权）时，应创建自定义 auth config，使用客户自己在 YNAB 开发者平台注册的 client ID 与 client secret。

官方指南 docs/kb/articles/toolkits-ynab.md 对此给出了两条硬性要求：

1. 使用自定义 OAuth 时，必须在 YNAB 应用侧注册当前 Composio auth-config 流程所显示的精确 redirect URI（exact redirect URI）。redirect URI 不匹配是 OAuth 授权码流程最常见的失败原因之一，任何大小写、路径或 query 的差异都可能导致授权失败。
2. 不能跳过 YNAB 侧的审核要求，详见下文"YNAB 应用限制与审核"一节。

参照 python/examples/auth_configs.py 中 custom auth 的通用写法，YNAB 的自定义 auth config 大致形如：

from composio import Composio

composio = Composio()

auth_config = composio.auth_configs.create(
    toolkit="ynab",
    options={
        "name": "Customer YNAB Auth",
        "type": "use_custom_auth",
        "auth_scheme": "OAUTH2",
        "credentials": {
            "client_id": "<customer-ynab-client-id>",
            "client_secret": "<customer-ynab-client-secret>",
            "oauth_redirect_uri": "<exact-redirect-uri-shown-by-composio>",
        },
    },
)
print(auth_config)

实际操作建议遵循以下顺序：

1. 先通过 Composio auth-config 流程（控制台或 SDK）发起创建，获取 Composio 当前为该应用分配的 redirect URI；
2. 将**该 URI 原样（exact）**登记到客户 YNAB 开发者应用的授权回调配置中；
3. 再填入 client ID、client secret 完成 auth config 创建；
4. 使用该 auth config 发起连接，验证授权码回调是否成功落地为 ACTIVE 的 connected account。

此外，Python SDK 提供了字段预检能力，可以在创建前查询该 toolkit 在该 auth scheme 下要求提供的字段，避免凭据字段遗漏：

required_fields = composio.toolkits.get_auth_config_creation_fields(
    toolkit="YNAB",
    auth_scheme="OAUTH2",
)
print(required_fields)

关于 redirect URI 的实操细节

由于官方指南强调 "register the exact redirect URI shown by the current Composio auth-config flow"，这里补充说明其含义：

• "current" 表示以当时的流程展示为准。Composio 的 auth-config 流程展示的 redirect URI 可能会随平台演进变化，因此不要凭记忆或旧文档硬编码，应以创建时流程实际返回的值为准；
• "exact" 表示逐字符一致。YNAB OAuth 服务器对回调地址做精确匹配，任何差异（协议 http/https、域名、端口、路径大小写、尾斜杠、额外 query 参数）都会导致回调校验失败；
• 一个常见误区是使用 YNAB 官方文档示例中的回调地址或通用占位符，这几乎必然失败。正确做法是先在 Composio 侧发起 auth config 创建，拿到真实的 redirect URI 后再去 YNAB 开发者应用后台登记。

YNAB 应用限制与审核：被判定 restricted 时怎么办

官方指南 docs/kb/articles/toolkits-ynab.md 专门指出了一种常见问题场景：

If YNAB reports that an application is restricted, review the YNAB app's current review and access-token restrictions.

当 YNAB 平台提示应用处于 restricted（受限）状态时，需要检查以下两类限制：

1. 应用审核要求（review requirements）：YNAB 对应用的审核要求取决于应用的分发范围。一个仅供其所有者本人使用的应用与一个分发给无关第三方用户的应用，在 YNAB 侧需要满足的 provider review（供应商审核）条件是不同的——后者通常要求更严格的审核与披露。因此在规划客户自持 OAuth 方案时，要提前确认该 YNAB 应用面向的最终用户范围，并据此判断审核工作量。
2. 访问令牌限制（access-token restrictions）：YNAB 可能对应用的 token 权限或使用范围施加额外限制，需要进入 YNAB 开发者平台查看当前应用的具体限制条款。

官方指南同时给出了一个明确的边界：

Do not promise a provider approval date.

即：不要向客户承诺 YNAB 的审核通过日期。provider 侧的审核时长由 YNAB 决定，不在 Composio 或接入方的控制范围内，任何对审批日期的承诺都可能造成交付风险。正确的做法是向客户说明审核为必经流程、时长由 YNAB 侧决定，并提前预留缓冲时间。

认证连接的生命周期与排错要点

YNAB 连接建立后，其状态由 Composio connected-account 生命周期管理。参考 docs/kb/articles/platform-connected-accounts.md 的定义：

• INITIALIZING：连接记录与托管授权流程已创建；
• INITIATED：用户已打开或推进授权流程；
• ACTIVE：授权流程完成且凭据已存储，连接可用；
• EXPIRED：流程超时，或连接无法再刷新/使用其授权。

针对 YNAB 这类 OAuth 工具，以下几点与认证配置直接相关：

• 连接过期不等于凭据错误。OAuth 连接可能因 provider 拒绝 refresh token、用户/管理员撤销应用、provider 安全策略吊销授权、轮换令牌链中断或自定义凭据变更而失效；重新连接可获得新的授权。若多个用户反复出现连接过期，应联系 Composio 支持并提供脱敏后的连接 ID 与时间戳，而不是反复重连。
• 不要依赖从 connected-account 响应中读取 provider token。Connected-account API 不会返回原始 access token / refresh token；需要通过工具执行或 Proxy Execute 调用 provider API。
• 如需用户重新授权，应发起新的 auth link 会话，并将用户重定向到返回的托管链接，等待连接变为 ACTIVE 后再使用其连接 ID。托管链接短期有效（约 10 分钟），超时后应生成新链接，而不是反复重试旧链接。

这些要点同样适用于 YNAB：如果你的 Agent 中的 YNAB 连接出现 EXPIRED，先读取 statusReason 区分是授权流程超时还是后台刷新失败，再决定是重新发起授权还是检查 YNAB 应用侧的限制。

小结：YNAB 认证配置决策路径

问题	决策
标准集成、无需品牌定制？	使用 Composio 托管 OAuth（use_composio_managed_auth）
客户需要控制 YNAB 开发者应用？	创建自定义 auth config，填入客户 client ID / client secret
自定义 OAuth 授权失败？	核对 redirect URI 是否与 Composio 流程展示的完全一致（exact）
YNAB 提示应用 restricted？	检查应用审核要求与 access-token 限制，评估最终用户分发范围
客户询问审核通过时间？	不承诺具体日期，说明时长由 YNAB 决定

接入 YNAB 的认证配置本质上只有两条路：托管 OAuth 省事可靠，适合大多数场景；客户自持 OAuth 可控性强，但需要承担 redirect URI 精确注册与 YNAB 应用审核两方面的额外责任。结合本文的配置示例与排错清单，即可在 Composio 上稳定地完成 YNAB 预算数据的 Agent 化接入。