Composio Kickbox 工具包凭证配置与 403 排障指南Single Verification API 认证字段与 EU 端点检查【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读本指南聚焦 Composio 平台中 Kickbox 工具包的认证接入与故障排查你将掌握KICKBOX_SINGLE_VERIFICATION_API工具所需的generic_api_key凭证字段的正确传参方式区别于上游 Kickbox API 文档中的apikey查询参数理解 Composio 当前采用 Bearer 头调用https://api.kickbox.com/v2/verify的实现细节并能系统排查 403Invalid API key错误包括字段形状、密钥有效性、权限、账户额度以及 EU-only 账户的区域端点差异。读完本文你可以独立完成 Kickbox 凭证的直连/自定义执行配置并在 EU 区域账户场景下准确判断是否需要向 Composio 支持升级。Kickbox 工具包与 Single Verification API 概览Kickbox 提供实时邮箱验证、列表清洗与质量评分的 API用于保障邮件送达率。在 Composio 平台中Kickbox 作为 email 分类下的工具包注册采用API_KEY认证方案当前版本包含两个工具docs/public/data/toolkits.json 中kickbox条目工具 slug名称用途KICKBOX_SINGLE_VERIFICATION_APIKickbox Single Verification通过 Kickbox 实时验证单个邮箱地址适合关键流程前的单条地址校验KICKBOX_CHECK_DISPOSABLECheck Disposable Email检查邮箱地址或域名是否来自一次性邮箱服务如 mailinator.com、trashmail.com此免费公共端点无需认证本指南核心针对需要认证的KICKBOX_SINGLE_VERIFICATION_API工具。凭证字段为什么是generic_api_key而不是api_key正确的直连/自定义凭证传参对于KICKBOX_SINGLE_VERIFICATION_APIComposio 的凭证字段名为generic_api_key。当客户使用直连direct或自定义凭证custom credential方式执行工具时应传入如下结构docs/kb/articles/toolkits-kickbox.md{ val: { generic_api_key: KICKBOX_API_KEY } }不要想当然地认为api_key就是 Composio 自定义凭证数据的正确字段名。这一点在 Composio 知识库中有更广泛的印证字段名是按工具包toolkit定制的不能假设所有 API Key / Bearer Token 类工具包都接受custom_connection_data.val.api_key。例如 Crowdin 工具包期望的是bearer_token而非api_keydocs/kb/articles/platform-custom-connection-data-fields.md。上游 API 与 Composio 实现的差异这里存在一个容易混淆的点Kickbox 提供商 API 自身的文档中认证参数名为apikey查询参数形式但 Kickbox 官方 quickstart 同时说明Authorization: Bearer API key头也被接受Composio 目前使用 Bearer 头并请求https://api.kickbox.com/v2/verify这对标准 Kickbox 账户是有效的。也就是说即便你在 Kickbox 侧文档看到的是apikey参数名在 Composio 侧构造凭证时仍必须使用generic_api_key字段二者是不同层级的命名约定。字段名的来源验证generic_api_key并非随机约定而是由工具包元数据声明的。Kickbox 工具包在connected_account_initiation阶段要求的必填字段即为generic_api_key显示名 Kickbox API Key类型 string必填见 docs/public/data/toolkits.json 中kickbox条目的authConfigDetails[].fields.connected_account_initiation.required。你还可以通过后端 API 动态核对任意工具包的必填字段curl --location https://backend.composio.dev/api/v3.1/toolkits/toolkit_slug \ --header x-api-key: COMPOSIO_API_KEY然后查看auth_config_details[].fields.connected_account_initiation.required该检查方法来自 docs/kb/articles/platform-custom-connection-data-fields.md。在 SDK 中配置 Kickbox 凭证除了直连/自定义凭证传参也可以通过 SDK 的 Connected Accounts API 创建 API Key 类型连接将generic_api_key存入凭证存储。以下两种语言示例均来自仓库自带示例代码。Python SDKpython/examples/connected_accounts.py 展示了创建 API Key 连接的完整流程import os from composio import Composio from composio.types import auth_scheme composio Composio() # Create a new connected account (API Key) connection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idos.environ[COMPOSIO_EXAMPLES_APIKEY_AUTH_CONFIG_ID], allow_multipleTrue, configauth_scheme.api_key( options{ generic_api_key: os.environ[COMPOSIO_EXAMPLES_APIKEY_PLACEHOLDER], }, ), ) print(connection_request)示例中还展示了如何动态获取某工具包 API Key 认证方案下的必填字段required_fields composio.toolkits.get_connected_account_initiation_fields( toolkitNOTION, auth_schemeAPI_KEY, ) print(required_fields)将toolkit替换为KICKBOX即可核对 Kickbox 的必填字段这与上文 curl 方式得到的connected_account_initiation.required信息一致。TypeScript SDKts/examples/connected-accounts/src/api-key.ts 中对应的写法import { AuthScheme, Composio } from composio/core; const composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY, }); const connectionRequest await composio.connectedAccounts.initiate(userId, authConfigId, { // Allow more than one connected account per user for this auth config allowMultiple: true, config: AuthScheme.APIKey({ generic_api_key: apiKey, }), }); console.log(connectionRequest);从源码看AuthScheme.APIKey构造器接收{ api_key?, generic_api_key? }参数并生成authScheme: API_KEY、val内含status: ACTIVE与所传字段的ConnectionDatats/packages/core/src/models/AuthScheme.ts。虽然构造器类型层面同时允许api_key与generic_api_key但最终工具包元数据决定的字段名才是实际生效的关键——对 Kickbox 而言必须是generic_api_key。工具执行与 Proxy Execute 场景在普通工具执行tools.execute中SDK 参数custom_connection_data类型tool_execute_params.CustomConnectionData即为直连凭证的入口docs/content/reference/sdk-reference/python/tools.mdx。在 Proxy Execute 场景下同样适用文档明确指出 Proxy execute requires auth context. Passconnected_account_id/connectedAccountId, or providecustom_connection_dataif youre supplying auth manuallydocs/content/docs/tools-direct/executing-tools.mdx。若你直接调用 Kickbox 的verify端点而非预定义工具也需要用同样的custom_connection_data结构注入generic_api_key。403Invalid API key系统排查步骤当 Kickbox 返回 403Invalid API key时请按以下顺序逐一验证docs/kb/articles/toolkits-kickbox.md核对脱敏后的custom_connection_data.val形状确认字段名确实是generic_api_key而不是api_key或apikey且值被正确放入val对象中。验证密钥有效性直接使用该 API Key 调用 Kickbox 上游接口确认密钥本身未过期、未撤销。检查密钥权限确认该 Key 具备调用 Single Verification API 的权限范围。检查账户/额度状态确认 Kickbox 账户有效、没有欠费或额度耗尽。判断账户是否 EU-only如果账户仅限欧盟区域将触发区域端点差异见下节。提示在向支持团队求助时请提供请求 ID 或日志 ID若无请求 ID则以脱敏形式移除密钥明文说明custom_connection_data的构造方式正如 docs/kb/articles/platform-custom-connection-data-fields.md 中建议的那样这能显著加速问题定位。EU-only 账户区域端点差异与已知限制Kickbox 官方文档说明EU-only 账户从app.eu.kickbox.com登录的账户必须使用api.eu.kickbox.com作为 API 端点。然而当前 Composio 的 Kickbox 工具包固定使用标准主机https://api.kickbox.com/v2/verify因此对标准非 EU-onlyKickbox 账户当前实现完全有效无需任何额外配置对 EU-only 账户标准主机可能无法通过认证或返回错误这属于工具包 base-URL/区域覆盖region gap层面的潜在问题。如果你的账户是 EU-only本文档建议联系 Composio 支持团队说明存在可能的工具包 base-URL/区域差异由平台侧评估是否需要在工具包层面增加 EU 端点支持。在平台支持到位之前EU-only 账户可考虑临时通过 Proxy Execute 或直连自定义凭证方式自行指向 EU 端点需注意 docs/content/docs/tools-direct/executing-tools.mdx 中关于端点同域校验的约束绝对 URL 必须与连接账户 base URL 使用相同 scheme 与可注册域名。参考文档与仓库线索本文主体依据docs/kb/articles/toolkits-kickbox.md即 KB 原文其公开知识来源为 docs/kb/source/toolkits/kickbox/public.mdMDX 渲染版本见 docs/content/kb/guide/toolkits-kickbox.mdx工具包元数据字段名、认证方案、工具列表docs/public/data/toolkits.json 中kickbox条目自定义凭证字段名通则字段名按工具包定制docs/kb/articles/platform-custom-connection-data-fields.mdPython SDK 凭证配置示例python/examples/connected_accounts.pyTypeScript SDK 凭证配置示例ts/examples/connected-accounts/src/api-key.tsAuthScheme.APIKey实现ts/packages/core/src/models/AuthScheme.tsProxy Execute 认证上下文要求docs/content/docs/tools-direct/executing-tools.mdxSDKexecute/proxy函数签名含custom_connection_data参数docs/content/reference/sdk-reference/python/tools.mdx说明Kickbox 上游的 Single Verification API 文档与 API Quickstart认证方式及 EU 端点说明是本文排障步骤的原始依据可在 Kickbox 官方文档站查阅此处不再重复粘贴外部链接。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考