跳转到正文
中文
获取 API 密钥
浏览文档

集成

智能体认证方式

通过 API Key 或 MCP OAuth 连接,无需付费查询即可验证访问,并在后续任务中复用。

本页内容

1. 选择并连接

已有连接可直接运行第 2 步的免费检查。否则,选择应用或智能体需要的访问方式。

接入对象使用方式谁保存凭据?
应用、SDK、CLI 或定时脚本所有者 API Key服务器密钥存储或 CLI 配置档
Codex 或 OpenClaw 研究工具MCP OAuth浏览器授权后由宿主保存
尚无账户、希望试用 FlashData 的智能体临时 API Key智能体保存的试用配置档;认领后改为所有者访问

在 API Keys 创建具有任务所需来源权限的密钥,或复用已有密钥。将其提供给 SDK,或由后端通过 X-API-Key 发送。第 2 步的 Bash 与 PowerShell 检查直接调用 API,无需安装 CLI。

该凭据可使用哪些来源?

普通 HTTP 请求及 API Key MCP 连接使用 X-API-Key。OAuth Bearer 令牌仅用于托管 MCP 端点。YouTube 下载需要具有 youtube_download 权限的所有者 API Key 及目标存储。

凭据可用来源
所有者 API Key该密钥获授的来源,包括获批后的 youtube_download。
临时 API Key仅限获授且符合试用资格的来源。通过当前身份响应读取 scopes。
MCP OAuthgoogle_search, youtube_search, youtube_metadata, youtube_transcript

在 CLI 保存密钥

CLI 已有访问或密钥管理器已提供 FLASHDATA_API_KEY 时,跳过导入。否则选择下方方式,后续命令保持使用相同 research 配置档。CLI 保存的密钥不会自动提供给 SDK 或本地 MCP 服务。

在终端的隐藏提示中粘贴密钥。

导入一次
flashdata auth login --profile research

2. 验证连接

在实际执行任务的环境运行免费检查。CLI 及 HTTP 检查使用 API Key;MCP 检查使用宿主自身保存的连接。

需要 Bash 与 cURL 7.76+。若环境已提供 FLASHDATA_API_KEY,跳过隐藏输入提示。在同一终端运行读取命令。

设置密钥 · 已配置可跳过
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
读取账户 JSON
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  'https://api.flashdata.dev/v2/api-access/identity' || exit
printf '\n'
)

检查 API Key 身份

HTTP 身份字段位于顶层。CLI JSON 中读取 data.identity.identity,并要求 data.accessVerified: true。仅有 HTTP 200 或 CLI ok: true 并不足够。

检查项所需结果
预期账户accountId 和 apiKeyId 对应你打算使用的账户与密钥。
可用访问access: ready
任务权限scopes 包含所需来源,例如 google_search。CLI 还在 data.identity.permittedSources 中列出允许的来源。
定时任务accountType: owned · installed: true · recurringAllowed: true

有效试用也是正常连接

试用可通过单次任务的访问检查,同时 recurringAllowed 为 false。读取实际 scopes 及到期时间;调度任务前认领已有试用。

临时身份 · 示例字段
{
  "accountType": "temporary",
  "access": "ready",
  "installed": false,
  "recurringAllowed": false,
  "scopes": [
    "google_search"
  ]
}

在 Codex 中查找连接

列出已配置的服务,再在新 Codex 会话使用 /mcp。运行上方 MCP 检查来验证凭据。

列出服务
codex mcp list

在 OpenClaw 中检查连接

探测已保存的服务,再在当前对话中运行上方 MCP 检查。

探测服务
openclaw mcp doctor flashdata --probe

3. 为后续任务复用访问

跨进程重启私密、持久地保留凭据存储。启用调度器前,在新进程重新检查访问。

凭据下次任务
所有者 API Key复用已保存密钥,无需 OAuth 刷新;到期或撤销后替换。
MCP OAuth宿主使用轮换刷新令牌刷新一小时有效的 OAuth 访问令牌。90 天授权过期或被撤销后需要重新连接。每个安装实例独立保存令牌,请勿在宿主间共享刷新令牌文件。
临时 API Key定时任务前完成所有者认领与凭据交接。复用原配置档,不要每次运行都重新注册。

调度前检查 CLI 任务

需要 Bash 与 jq。将 SOURCE 设为任务来源。脚本默认使用 research;其他配置档或状态目录可设置 FLASHDATA_PROFILE 及 FLASHDATA_STATE_DIR。退出码为 0 且输出身份 JSON,表示所有者密钥已就绪、已安装并获授该来源。配置调度器在其他退出码时停止。不提交查询。

新进程访问检查 · Bash
(
set -euo pipefail
SOURCE=google_search
args=(--profile "${FLASHDATA_PROFILE:-research}" --json --non-interactive)
if [[ -n "${FLASHDATA_STATE_DIR:-}" ]]; then
  args+=(--state-dir "$FLASHDATA_STATE_DIR")
fi

flashdata auth status "${args[@]}" |
  jq -e --arg source "$SOURCE" '
    select(.ok == true and .data.accessVerified == true)
    | .data.identity as $auth
    | $auth.identity
    | select(.accountType == "owned" and .access == "ready"
        and .installed == true and .recurringAllowed == true
        and ((.scopes // []) | index($source) != null)
        and (($auth.permittedSources // []) | index($source) != null))
    | {accountId, apiKeyId, scopes, recurringAllowed, expiresAt}'
)

如果仍处于试用阶段

使用原配置档完成试用及认领指南。所有者批准并完成凭据交接后,免费检查应显示 owned 访问及 recurringAllowed: true。后续请求使用所有者共享余额,未用完的试用 Credits 不会转移。MCP OAuth 登录是独立连接,不会认领此试用。

撤销访问

先暂停定时任务,再于下方对应位置撤销凭据。清除本地访问前,从新进程或新会话重复免费检查,应返回认证失败或要求重连;检查期间不要批准新连接。仅本地退出不会撤销服务器访问。

连接撤销位置
MCP OAuth设置 → 已连接应用 → 对应应用授权。
已认领的智能体 API Key设置 → 已连接应用 → 智能体连接。
账户 API KeyAPI Keys → 此集成使用的密钥。

修复检查失败

结果操作
accessVerified: false检查 phase 及 nextCommand。密钥可用前,待完成配置档也可能返回 ok: true。完成已保存的注册或认领,保留相同配置档。
access: blocked即使 HTTP 响应为 200 也应停止。在控制台检查账户或连接,不要将身份响应视为查询许可。
accountType: temporary符合资格的单次任务可使用试用。调度前先认领;新的 OAuth 连接不会认领此配置档。
installed: false所有者批准后,以原配置档及状态目录运行 flashdata auth finish --wait,再重复检查。
401 / invalid_grant在原宿主重新连接已过期或撤销的凭据。不要另建试用绕过。
403 / source_forbidden检查密钥 scopes 或 OAuth 来源列表。YouTube 下载使用所有者 API Key。
访问有效,但余额为零认证成功。付费任务前检查 Billing,无需替换有效密钥。