REST：换 Bearer 并用 /entities 搜公司

你将得到什么

• 一对 REST API 的 Client ID / Client secret（仅创建时完整可见）
• 一个可用的 ACCESS_TOKEN（token_type=Bearer）
• 一次成功的公司搜索 JSON（entities 数组含 entity_id / name / score）

开始前准备

1. 已能登录 Finbar Web 应用，并打开 API panel。
2. 本机终端有 curl；示例使用 --fail-with-body（curl 7.76+）。
3. 准备私密环境变量文件或 shell 会话；勿把 secret 写进仓库或命令行历史可被他人看到的位置。

核心事实（先记住）

OAuth scopes（请求时用完整 URL 名）

文档里的短名如 datasets:read 仅为可读性；发 token 请求时用上表完整名。

步骤 1：在 Web 应用创建 REST 凭证

1. 打开 Finbar Web → API panel。
2. Create credential → 起名 → 选择 REST API。
3. 立刻保存 Client ID 与 Client secret（secret 仅在创建/轮换时显示）。

对照结果：面板出现该凭证；本机已安全存下 ID/secret（如密钥管理器或 chmod 600 的本地文件）。

官方提醒：secret 只用在服务端/脚本，不要放进浏览器前端或源码仓库。

步骤 2：用 client credentials 换 access_token

将 CLIENT_ID / CLIENT_SECRET 设为你刚保存的值。官方用 --config - 从 stdin 读用户名密码，避免 secret 出现在进程参数里：

curl --fail-with-body --silent --show-error \
  --config - \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=https://api.finbar.com/entities:read https://api.finbar.com/documents:read https://api.finbar.com/datasets:read' \
  https://auth.finbar.com/oauth2/token <<EOF_TOKEN
user = "$CLIENT_ID:$CLIENT_SECRET"
EOF_TOKEN

对照结果（JSON 字段）：

导出供后续使用：

export ACCESS_TOKEN='粘贴返回的 access_token'

注意：为 MCP 签发的 token 不能用于 REST API。

步骤 3：搜索公司（官方 quickstart）

curl --fail-with-body --silent --show-error --get \
  'https://api.finbar.com/v1/entities' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'q=Apple' \
  --data-urlencode 'limit=5'

对照结果（结构示意；ID/分数以你账号数据为准）：

{
  "entities": [
    {
      "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
      "name": "Apple Inc.",
      "score": 0.98
    }
  ],
  "next_cursor": "eyJ2IjoxLCJiaW5kaW5nIjoiLi4uIn0"
}

要点：

• q 为搜索文本，limit 为期望条数
• 后续接口用 entity_id，不能用公司名或 ticker 替代
• entities 为空：换名称/代码再搜；多条匹配时先核对 name 再取 ID

步骤 4：选好 entity 后可去哪（官方表）

分页与错误处理见 Errors and pagination。

轮换与吊销

• Rotate：换新 ID/secret 后更新应用；旧对立即无法换 token。
• Revoke：不再需要时吊销。
• 缺权限：创建带齐权限的新凭证（rotation 会保留原权限集合）。

本课检查清单

• REST 凭证已创建，secret 未泄露到 Git/前端
• token 响应含 access_token 且 token_type=Bearer
• GET /v1/entities?q=Apple 返回非空 entities，并记下一条 entity_id

延伸阅读

• API and MCP overview
• MCP tools and workflows
• Web app / Excel add-in